chore(i18n): refresh fr translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
a7d6cac666
commit
13131876af
@ -1,56 +1,56 @@
|
||||
---
|
||||
read_when:
|
||||
- Travailler sur les fonctionnalités du canal Microsoft Teams
|
||||
summary: État de prise en charge du bot Microsoft Teams, capacités et configuration
|
||||
- Travail sur les fonctionnalités du canal Microsoft Teams
|
||||
summary: Statut de prise en charge, capacités et configuration du bot Microsoft Teams
|
||||
title: Microsoft Teams
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:37:07Z"
|
||||
generated_at: "2026-04-12T00:18:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf
|
||||
source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79
|
||||
source_path: channels/msteams.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Microsoft Teams
|
||||
|
||||
> "Vous qui entrez ici, abandonnez tout espoir."
|
||||
> « Vous qui entrez ici, abandonnez tout espoir. »
|
||||
|
||||
Mise à jour : 2026-01-21
|
||||
Mis à jour : 2026-03-25
|
||||
|
||||
Statut : le texte + les pièces jointes DM sont pris en charge ; l’envoi de fichiers dans les canaux/groupes nécessite `sharePointSiteId` + les autorisations Graph (voir [Sending files in group chats](#sending-files-in-group-chats)). Les sondages sont envoyés via des Adaptive Cards. Les actions de message exposent `upload-file` explicite pour les envois centrés sur les fichiers.
|
||||
Statut : le texte + les pièces jointes en MP sont pris en charge ; l’envoi de fichiers dans les canaux/groupes nécessite `sharePointSiteId` + des autorisations Graph (voir [Envoi de fichiers dans les conversations de groupe](#sending-files-in-group-chats)). Les sondages sont envoyés via des cartes adaptatives. Les actions de message exposent un `upload-file` explicite pour les envois d’abord centrés sur les fichiers.
|
||||
|
||||
## Plugin intégré
|
||||
|
||||
Microsoft Teams est fourni comme plugin intégré dans les versions actuelles d’OpenClaw, donc
|
||||
aucune installation séparée n’est requise dans la build empaquetée normale.
|
||||
aucune installation séparée n’est requise dans la build packagée standard.
|
||||
|
||||
Si vous utilisez une ancienne build ou une installation personnalisée qui exclut Teams intégré,
|
||||
Si vous utilisez une build plus ancienne ou une installation personnalisée qui exclut Teams intégré,
|
||||
installez-le manuellement :
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/msteams
|
||||
```
|
||||
|
||||
Extraction locale (lors d’une exécution à partir d’un dépôt git) :
|
||||
Checkout local (lors d’une exécution depuis un dépôt git) :
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/msteams-plugin
|
||||
```
|
||||
|
||||
Détails : [Plugins](/tools/plugin)
|
||||
Détails : [Plugins](/fr/tools/plugin)
|
||||
|
||||
## Configuration rapide (débutant)
|
||||
|
||||
1. Assurez-vous que le plugin Microsoft Teams est disponible.
|
||||
- Les versions empaquetées actuelles d’OpenClaw l’intègrent déjà.
|
||||
- Les installations anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus.
|
||||
- Les versions packagées actuelles d’OpenClaw l’intègrent déjà.
|
||||
- Les installations plus anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus.
|
||||
2. Créez un **Azure Bot** (ID d’application + secret client + ID de locataire).
|
||||
3. Configurez OpenClaw avec ces identifiants.
|
||||
4. Exposez `/api/messages` (port 3978 par défaut) via une URL publique ou un tunnel.
|
||||
5. Installez le package d’application Teams et démarrez la gateway.
|
||||
5. Installez le package d’application Teams et démarrez la passerelle.
|
||||
|
||||
Configuration minimale :
|
||||
Configuration minimale (secret client) :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -66,19 +66,21 @@ Configuration minimale :
|
||||
}
|
||||
```
|
||||
|
||||
Remarque : les discussions de groupe sont bloquées par défaut (`channels.msteams.groupPolicy: "allowlist"`). Pour autoriser les réponses de groupe, définissez `channels.msteams.groupAllowFrom` (ou utilisez `groupPolicy: "open"` pour autoriser n’importe quel membre, avec filtrage par mention).
|
||||
Pour les déploiements en production, envisagez d’utiliser [l’authentification fédérée](#federated-authentication-certificate--managed-identity) (certificat ou identité managée) au lieu des secrets clients.
|
||||
|
||||
Remarque : les conversations de groupe sont bloquées par défaut (`channels.msteams.groupPolicy: "allowlist"`). Pour autoriser les réponses en groupe, définissez `channels.msteams.groupAllowFrom` (ou utilisez `groupPolicy: "open"` pour autoriser n’importe quel membre, avec obligation de mention).
|
||||
|
||||
## Objectifs
|
||||
|
||||
- Parler à OpenClaw via des DM, des discussions de groupe ou des canaux Teams.
|
||||
- Garder un routage déterministe : les réponses reviennent toujours au canal d’où elles proviennent.
|
||||
- Utiliser par défaut un comportement de canal sûr (mentions requises sauf configuration contraire).
|
||||
- Parler à OpenClaw via des MP Teams, des conversations de groupe ou des canaux.
|
||||
- Garder un routage déterministe : les réponses reviennent toujours au canal depuis lequel elles sont arrivées.
|
||||
- Adopter par défaut un comportement sûr dans les canaux (mentions requises sauf configuration contraire).
|
||||
|
||||
## Écritures de configuration
|
||||
|
||||
Par défaut, Microsoft Teams est autorisé à écrire des mises à jour de configuration déclenchées par `/config set|unset` (nécessite `commands.config: true`).
|
||||
|
||||
Désactivez-les avec :
|
||||
Désactiver avec :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -86,20 +88,20 @@ Désactivez-les avec :
|
||||
}
|
||||
```
|
||||
|
||||
## Contrôle d’accès (DM + groupes)
|
||||
## Contrôle d’accès (MP + groupes)
|
||||
|
||||
**Accès DM**
|
||||
**Accès MP**
|
||||
|
||||
- Par défaut : `channels.msteams.dmPolicy = "pairing"`. Les expéditeurs inconnus sont ignorés jusqu’à approbation.
|
||||
- `channels.msteams.allowFrom` doit utiliser des ID d’objet AAD stables.
|
||||
- Les UPN/noms d’affichage sont modifiables ; la correspondance directe est désactivée par défaut et n’est activée qu’avec `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- L’assistant peut résoudre les noms en ID via Microsoft Graph lorsque les identifiants le permettent.
|
||||
|
||||
**Accès de groupe**
|
||||
**Accès groupe**
|
||||
|
||||
- Par défaut : `channels.msteams.groupPolicy = "allowlist"` (bloqué tant que vous n’ajoutez pas `groupAllowFrom`). Utilisez `channels.defaults.groupPolicy` pour remplacer la valeur par défaut lorsqu’elle n’est pas définie.
|
||||
- `channels.msteams.groupAllowFrom` contrôle quels expéditeurs peuvent déclencher l’agent dans les discussions/canaux de groupe (solution de repli vers `channels.msteams.allowFrom`).
|
||||
- Définissez `groupPolicy: "open"` pour autoriser n’importe quel membre (toujours filtré par mention par défaut).
|
||||
- Par défaut : `channels.msteams.groupPolicy = "allowlist"` (bloqué sauf si vous ajoutez `groupAllowFrom`). Utilisez `channels.defaults.groupPolicy` pour remplacer la valeur par défaut lorsqu’elle n’est pas définie.
|
||||
- `channels.msteams.groupAllowFrom` contrôle quels expéditeurs peuvent déclencher des réponses dans les conversations de groupe/canaux (revient à `channels.msteams.allowFrom` en secours).
|
||||
- Définissez `groupPolicy: "open"` pour autoriser n’importe quel membre (toujours soumis à l’obligation de mention par défaut).
|
||||
- Pour n’autoriser **aucun canal**, définissez `channels.msteams.groupPolicy: "disabled"`.
|
||||
|
||||
Exemple :
|
||||
@ -115,14 +117,14 @@ Exemple :
|
||||
}
|
||||
```
|
||||
|
||||
**Teams + liste d’autorisation de canaux**
|
||||
**Liste d’autorisation Teams + canal**
|
||||
|
||||
- Cadrez les réponses de groupe/canal en listant les équipes et les canaux sous `channels.msteams.teams`.
|
||||
- Définissez la portée des réponses de groupe/canal en répertoriant les équipes et les canaux sous `channels.msteams.teams`.
|
||||
- Les clés doivent utiliser des ID d’équipe stables et des ID de conversation de canal.
|
||||
- Lorsque `groupPolicy="allowlist"` et qu’une liste d’autorisation d’équipes est présente, seules les équipes/canaux listés sont acceptés (avec filtrage par mention).
|
||||
- L’assistant de configuration accepte les entrées `Team/Channel` et les enregistre pour vous.
|
||||
- Au démarrage, OpenClaw résout les noms d’équipes/canaux et les noms d’utilisateurs des listes d’autorisation en ID (lorsque les autorisations Graph le permettent)
|
||||
et journalise le mappage ; les noms d’équipes/canaux non résolus sont conservés tels qu’ils ont été saisis mais ignorés pour le routage par défaut, sauf si `channels.msteams.dangerouslyAllowNameMatching: true` est activé.
|
||||
- Quand `groupPolicy="allowlist"` et qu’une liste d’autorisation d’équipes est présente, seules les équipes/canaux répertoriés sont acceptés (avec obligation de mention).
|
||||
- L’assistant de configuration accepte des entrées `Team/Channel` et les stocke pour vous.
|
||||
- Au démarrage, OpenClaw résout les noms d’équipe/canal et les noms d’utilisateurs de la liste d’autorisation en ID (lorsque les autorisations Graph le permettent)
|
||||
et consigne la correspondance ; les noms d’équipe/canal non résolus sont conservés tels qu’ils ont été saisis mais ignorés pour le routage par défaut, sauf si `channels.msteams.dangerouslyAllowNameMatching: true` est activé.
|
||||
|
||||
Exemple :
|
||||
|
||||
@ -146,60 +148,202 @@ Exemple :
|
||||
## Fonctionnement
|
||||
|
||||
1. Assurez-vous que le plugin Microsoft Teams est disponible.
|
||||
- Les versions empaquetées actuelles d’OpenClaw l’intègrent déjà.
|
||||
- Les installations anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus.
|
||||
- Les versions packagées actuelles d’OpenClaw l’intègrent déjà.
|
||||
- Les installations plus anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus.
|
||||
2. Créez un **Azure Bot** (ID d’application + secret + ID de locataire).
|
||||
3. Construisez un **package d’application Teams** qui référence le bot et inclut les autorisations RSC ci-dessous.
|
||||
4. Téléversez/installez l’application Teams dans une équipe (ou dans l’étendue personnelle pour les DM).
|
||||
5. Configurez `msteams` dans `~/.openclaw/openclaw.json` (ou via des variables d’environnement) et démarrez la gateway.
|
||||
6. La gateway écoute par défaut le trafic webhook Bot Framework sur `/api/messages`.
|
||||
3. Créez un **package d’application Teams** qui référence le bot et inclut les autorisations RSC ci-dessous.
|
||||
4. Téléversez/installez l’application Teams dans une équipe (ou dans la portée personnelle pour les MP).
|
||||
5. Configurez `msteams` dans `~/.openclaw/openclaw.json` (ou les variables d’environnement) et démarrez la passerelle.
|
||||
6. La passerelle écoute le trafic webhook Bot Framework sur `/api/messages` par défaut.
|
||||
|
||||
## Configuration d’Azure Bot (prérequis)
|
||||
## Configuration Azure Bot (prérequis)
|
||||
|
||||
Avant de configurer OpenClaw, vous devez créer une ressource Azure Bot.
|
||||
|
||||
### Étape 1 : créer Azure Bot
|
||||
|
||||
1. Accédez à [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
|
||||
1. Accédez à [Créer Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
|
||||
2. Remplissez l’onglet **Basics** :
|
||||
|
||||
| Champ | Valeur |
|
||||
| ------------------ | -------------------------------------------------------- |
|
||||
| **Bot handle** | Nom de votre bot, par ex. `openclaw-msteams` (doit être unique) |
|
||||
| **Bot handle** | Votre nom de bot, par ex. `openclaw-msteams` (doit être unique) |
|
||||
| **Subscription** | Sélectionnez votre abonnement Azure |
|
||||
| **Resource group** | Créez-en un nouveau ou utilisez un groupe existant |
|
||||
| **Resource group** | Créez-en un nouveau ou utilisez un existant |
|
||||
| **Pricing tier** | **Free** pour le développement/test |
|
||||
| **Type of App** | **Single Tenant** (recommandé - voir la note ci-dessous) |
|
||||
| **Type of App** | **Single Tenant** (recommandé - voir la remarque ci-dessous) |
|
||||
| **Creation type** | **Create new Microsoft App ID** |
|
||||
|
||||
> **Avis de dépréciation :** la création de nouveaux bots multi-locataires a été dépréciée après le 2025-07-31. Utilisez **Single Tenant** pour les nouveaux bots.
|
||||
> **Avis de dépréciation :** la création de nouveaux bots multilocataires a été dépréciée après le 2025-07-31. Utilisez **Single Tenant** pour les nouveaux bots.
|
||||
|
||||
3. Cliquez sur **Review + create** → **Create** (attendez ~1-2 minutes)
|
||||
|
||||
### Étape 2 : récupérer les identifiants
|
||||
|
||||
1. Accédez à votre ressource Azure Bot → **Configuration**
|
||||
2. Copiez **Microsoft App ID** → c’est votre `appId`
|
||||
2. Copiez **Microsoft App ID** → il s’agit de votre `appId`
|
||||
3. Cliquez sur **Manage Password** → accédez à l’enregistrement d’application
|
||||
4. Sous **Certificates & secrets** → **New client secret** → copiez la **Value** → c’est votre `appPassword`
|
||||
5. Accédez à **Overview** → copiez **Directory (tenant) ID** → c’est votre `tenantId`
|
||||
4. Sous **Certificates & secrets** → **New client secret** → copiez la **Value** → il s’agit de votre `appPassword`
|
||||
5. Accédez à **Overview** → copiez **Directory (tenant) ID** → il s’agit de votre `tenantId`
|
||||
|
||||
### Étape 3 : configurer le point de terminaison de messagerie
|
||||
|
||||
1. Dans Azure Bot → **Configuration**
|
||||
2. Définissez **Messaging endpoint** sur votre URL webhook :
|
||||
2. Définissez **Messaging endpoint** sur votre URL de webhook :
|
||||
- Production : `https://your-domain.com/api/messages`
|
||||
- Développement local : utilisez un tunnel (voir [Local Development](#local-development-tunneling) ci-dessous)
|
||||
- Développement local : utilisez un tunnel (voir [Développement local](#local-development-tunneling) ci-dessous)
|
||||
|
||||
### Étape 4 : activer le canal Teams
|
||||
|
||||
1. Dans Azure Bot → **Channels**
|
||||
2. Cliquez sur **Microsoft Teams** → Configure → Save
|
||||
3. Acceptez les Conditions d’utilisation
|
||||
3. Acceptez les conditions d’utilisation
|
||||
|
||||
## Développement local (tunneling)
|
||||
## Authentification fédérée (certificat + identité managée)
|
||||
|
||||
Teams ne peut pas joindre `localhost`. Utilisez un tunnel pour le développement local :
|
||||
> Ajouté dans 2026.3.24
|
||||
|
||||
Pour les déploiements en production, OpenClaw prend en charge **l’authentification fédérée** comme alternative plus sécurisée aux secrets clients. Deux méthodes sont disponibles :
|
||||
|
||||
### Option A : authentification basée sur un certificat
|
||||
|
||||
Utilisez un certificat PEM enregistré dans votre enregistrement d’application Entra ID.
|
||||
|
||||
**Configuration :**
|
||||
|
||||
1. Générez ou obtenez un certificat (format PEM avec clé privée).
|
||||
2. Dans Entra ID → Enregistrement d’application → **Certificates & secrets** → **Certificates** → téléversez le certificat public.
|
||||
|
||||
**Config :**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
certificatePath: "/path/to/cert.pem",
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Variables d’environnement :**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem`
|
||||
|
||||
### Option B : Azure Managed Identity
|
||||
|
||||
Utilisez Azure Managed Identity pour une authentification sans mot de passe. C’est idéal pour les déploiements sur une infrastructure Azure (AKS, App Service, machines virtuelles Azure) où une identité managée est disponible.
|
||||
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Le pod/VM du bot dispose d’une identité managée (attribuée par le système ou par l’utilisateur).
|
||||
2. Un **identifiant d’identité fédérée** lie l’identité managée à l’enregistrement d’application Entra ID.
|
||||
3. À l’exécution, OpenClaw utilise `@azure/identity` pour acquérir des jetons depuis le point de terminaison Azure IMDS (`169.254.169.254`).
|
||||
4. Le jeton est transmis au SDK Teams pour l’authentification du bot.
|
||||
|
||||
**Prérequis :**
|
||||
|
||||
- Infrastructure Azure avec identité managée activée (identité de charge de travail AKS, App Service, VM)
|
||||
- Identifiant d’identité fédérée créé sur l’enregistrement d’application Entra ID
|
||||
- Accès réseau à IMDS (`169.254.169.254:80`) depuis le pod/VM
|
||||
|
||||
**Config (identité managée attribuée par le système) :**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
useManagedIdentity: true,
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Config (identité managée attribuée par l’utilisateur) :**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
useManagedIdentity: true,
|
||||
managedIdentityClientId: "<MI_CLIENT_ID>",
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Variables d’environnement :**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY=true`
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>` (uniquement pour les identités attribuées par l’utilisateur)
|
||||
|
||||
### Configuration d’AKS Workload Identity
|
||||
|
||||
Pour les déploiements AKS utilisant une identité de charge de travail :
|
||||
|
||||
1. **Activez l’identité de charge de travail** sur votre cluster AKS.
|
||||
2. **Créez un identifiant d’identité fédérée** sur l’enregistrement d’application Entra ID :
|
||||
|
||||
```bash
|
||||
az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
|
||||
"name": "my-bot-workload-identity",
|
||||
"issuer": "<AKS_OIDC_ISSUER_URL>",
|
||||
"subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",
|
||||
"audiences": ["api://AzureADTokenExchange"]
|
||||
}'
|
||||
```
|
||||
|
||||
3. **Annotez le compte de service Kubernetes** avec l’ID client de l’application :
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: my-bot-sa
|
||||
annotations:
|
||||
azure.workload.identity/client-id: "<APP_CLIENT_ID>"
|
||||
```
|
||||
|
||||
4. **Ajoutez un libellé au pod** pour l’injection de l’identité de charge de travail :
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
labels:
|
||||
azure.workload.identity/use: "true"
|
||||
```
|
||||
|
||||
5. **Assurez l’accès réseau** à IMDS (`169.254.169.254`) — si vous utilisez NetworkPolicy, ajoutez une règle de sortie autorisant le trafic vers `169.254.169.254/32` sur le port 80.
|
||||
|
||||
### Comparaison des types d’authentification
|
||||
|
||||
| Méthode | Config | Avantages | Inconvénients |
|
||||
| -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- |
|
||||
| **Secret client** | `appPassword` | Configuration simple | Rotation des secrets requise, moins sûr |
|
||||
| **Certificat** | `authType: "federated"` + `certificatePath` | Aucun secret partagé sur le réseau | Gestion des certificats plus lourde |
|
||||
| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | Sans mot de passe, aucun secret à gérer | Infrastructure Azure requise |
|
||||
|
||||
**Comportement par défaut :** lorsque `authType` n’est pas défini, OpenClaw utilise par défaut l’authentification par secret client. Les configurations existantes continuent de fonctionner sans modification.
|
||||
|
||||
## Développement local (tunnel)
|
||||
|
||||
Teams ne peut pas atteindre `localhost`. Utilisez un tunnel pour le développement local :
|
||||
|
||||
**Option A : ngrok**
|
||||
|
||||
@ -213,22 +357,22 @@ ngrok http 3978
|
||||
|
||||
```bash
|
||||
tailscale funnel 3978
|
||||
# Utilisez votre URL de funnel Tailscale comme point de terminaison de messagerie
|
||||
# Utilisez votre URL Tailscale funnel comme point de terminaison de messagerie
|
||||
```
|
||||
|
||||
## Teams Developer Portal (alternative)
|
||||
## Portail des développeurs Teams (alternative)
|
||||
|
||||
Au lieu de créer manuellement un ZIP de manifeste, vous pouvez utiliser le [Teams Developer Portal](https://dev.teams.microsoft.com/apps) :
|
||||
Au lieu de créer manuellement un ZIP de manifeste, vous pouvez utiliser le [Portail des développeurs Teams](https://dev.teams.microsoft.com/apps) :
|
||||
|
||||
1. Cliquez sur **+ New app**
|
||||
2. Remplissez les informations de base (nom, description, informations développeur)
|
||||
2. Renseignez les informations de base (nom, description, informations sur le développeur)
|
||||
3. Accédez à **App features** → **Bot**
|
||||
4. Sélectionnez **Enter a bot ID manually** et collez votre Azure Bot App ID
|
||||
5. Cochez les étendues : **Personal**, **Team**, **Group Chat**
|
||||
4. Sélectionnez **Enter a bot ID manually** et collez votre ID d’application Azure Bot
|
||||
5. Cochez les portées : **Personal**, **Team**, **Group Chat**
|
||||
6. Cliquez sur **Distribute** → **Download app package**
|
||||
7. Dans Teams : **Apps** → **Manage your apps** → **Upload a custom app** → sélectionnez le ZIP
|
||||
|
||||
C’est souvent plus simple que de modifier manuellement des manifestes JSON.
|
||||
C’est souvent plus simple que de modifier des manifestes JSON à la main.
|
||||
|
||||
## Tester le bot
|
||||
|
||||
@ -240,28 +384,28 @@ C’est souvent plus simple que de modifier manuellement des manifestes JSON.
|
||||
|
||||
**Option B : Teams (après installation de l’application)**
|
||||
|
||||
1. Installez l’application Teams (chargement latéral ou catalogue de l’organisation)
|
||||
2. Trouvez le bot dans Teams et envoyez un DM
|
||||
3. Vérifiez les journaux de la gateway pour voir l’activité entrante
|
||||
1. Installez l’application Teams (chargement latéral ou catalogue d’organisation)
|
||||
2. Trouvez le bot dans Teams et envoyez un MP
|
||||
3. Vérifiez les journaux de la passerelle pour l’activité entrante
|
||||
|
||||
## Configuration (texte uniquement minimal)
|
||||
## Configuration (minimale, texte uniquement)
|
||||
|
||||
1. **Assurez-vous que le plugin Microsoft Teams est disponible**
|
||||
- Les versions empaquetées actuelles d’OpenClaw l’intègrent déjà.
|
||||
- Les installations anciennes/personnalisées peuvent l’ajouter manuellement :
|
||||
- Les versions packagées actuelles d’OpenClaw l’intègrent déjà.
|
||||
- Les installations plus anciennes/personnalisées peuvent l’ajouter manuellement :
|
||||
- Depuis npm : `openclaw plugins install @openclaw/msteams`
|
||||
- Depuis une extraction locale : `openclaw plugins install ./path/to/local/msteams-plugin`
|
||||
- Depuis un checkout local : `openclaw plugins install ./path/to/local/msteams-plugin`
|
||||
|
||||
2. **Enregistrement du bot**
|
||||
- Créez un Azure Bot (voir ci-dessus) et notez :
|
||||
- ID d’application
|
||||
- Secret client (mot de passe de l’application)
|
||||
- ID de locataire (single-tenant)
|
||||
- ID de locataire (locataire unique)
|
||||
|
||||
3. **Manifeste d’application Teams**
|
||||
- Incluez une entrée `bot` avec `botId = <App ID>`.
|
||||
- Étendues : `personal`, `team`, `groupChat`.
|
||||
- `supportsFiles: true` (requis pour la gestion des fichiers dans l’étendue personnelle).
|
||||
- Portées : `personal`, `team`, `groupChat`.
|
||||
- `supportsFiles: true` (requis pour la gestion des fichiers dans la portée personnelle).
|
||||
- Ajoutez les autorisations RSC (ci-dessous).
|
||||
- Créez les icônes : `outline.png` (32x32) et `color.png` (192x192).
|
||||
- Compressez ensemble les trois fichiers : `manifest.json`, `outline.png`, `color.png`.
|
||||
@ -286,39 +430,44 @@ C’est souvent plus simple que de modifier manuellement des manifestes JSON.
|
||||
- `MSTEAMS_APP_ID`
|
||||
- `MSTEAMS_APP_PASSWORD`
|
||||
- `MSTEAMS_TENANT_ID`
|
||||
- `MSTEAMS_AUTH_TYPE` (facultatif : `"secret"` ou `"federated"`)
|
||||
- `MSTEAMS_CERTIFICATE_PATH` (fédéré + certificat)
|
||||
- `MSTEAMS_CERTIFICATE_THUMBPRINT` (facultatif, non requis pour l’authentification)
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY` (fédéré + identité managée)
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (uniquement pour l’identité managée attribuée par l’utilisateur)
|
||||
|
||||
5. **Point de terminaison du bot**
|
||||
- Définissez le Messaging Endpoint d’Azure Bot sur :
|
||||
- `https://<host>:3978/api/messages` (ou votre chemin/port choisi).
|
||||
- Définissez le point de terminaison de messagerie Azure Bot sur :
|
||||
- `https://<host>:3978/api/messages` (ou le chemin/port de votre choix).
|
||||
|
||||
6. **Exécuter la gateway**
|
||||
6. **Exécuter la passerelle**
|
||||
- Le canal Teams démarre automatiquement lorsque le plugin intégré ou installé manuellement est disponible et que la configuration `msteams` existe avec les identifiants.
|
||||
|
||||
## Action d’informations sur les membres
|
||||
## Action d’informations sur le membre
|
||||
|
||||
OpenClaw expose une action `member-info` reposant sur Graph pour Microsoft Teams afin que les agents et automatisations puissent résoudre directement depuis Microsoft Graph les détails des membres d’un canal (nom d’affichage, e-mail, rôle).
|
||||
OpenClaw expose une action `member-info` adossée à Graph pour Microsoft Teams afin que les agents et automatisations puissent résoudre directement depuis Microsoft Graph les détails des membres du canal (nom d’affichage, e-mail, rôle).
|
||||
|
||||
Exigences :
|
||||
|
||||
- Autorisation RSC `Member.Read.Group` (déjà présente dans le manifeste recommandé)
|
||||
- Pour les recherches inter-équipes : autorisation d’application Graph `User.Read.All` avec consentement administrateur
|
||||
|
||||
L’action est contrôlée par `channels.msteams.actions.memberInfo` (activée par défaut lorsque les identifiants Graph sont disponibles).
|
||||
L’action est contrôlée par `channels.msteams.actions.memberInfo` (par défaut : activée lorsque des identifiants Graph sont disponibles).
|
||||
|
||||
## Contexte d’historique
|
||||
|
||||
- `channels.msteams.historyLimit` contrôle combien de messages récents de canal/groupe sont encapsulés dans le prompt.
|
||||
- Utilise `messages.groupChat.historyLimit` comme solution de repli. Définissez `0` pour désactiver (50 par défaut).
|
||||
- `channels.msteams.historyLimit` contrôle le nombre de messages récents de canal/groupe encapsulés dans le prompt.
|
||||
- Revient à `messages.groupChat.historyLimit`. Définissez `0` pour désactiver (50 par défaut).
|
||||
- L’historique de fil récupéré est filtré par les listes d’autorisation d’expéditeurs (`allowFrom` / `groupAllowFrom`), de sorte que l’initialisation du contexte du fil n’inclut que les messages d’expéditeurs autorisés.
|
||||
- Le contexte de pièce jointe citée (`ReplyTo*` dérivé du HTML de réponse Teams) est actuellement transmis tel que reçu.
|
||||
- En d’autres termes, les listes d’autorisation contrôlent qui peut déclencher l’agent ; seuls certains chemins de contexte complémentaire sont filtrés aujourd’hui.
|
||||
- L’historique DM peut être limité avec `channels.msteams.dmHistoryLimit` (tours utilisateur). Remplacements par utilisateur : `channels.msteams.dms["<user_id>"].historyLimit`.
|
||||
- En d’autres termes, les listes d’autorisation contrôlent qui peut déclencher l’agent ; seuls certains chemins de contexte supplémentaire sont filtrés aujourd’hui.
|
||||
- L’historique des MP peut être limité avec `channels.msteams.dmHistoryLimit` (tours utilisateur). Remplacements par utilisateur : `channels.msteams.dms["<user_id>"].historyLimit`.
|
||||
|
||||
## Autorisations RSC Teams actuelles (manifeste)
|
||||
|
||||
Ce sont les **autorisations resourceSpecific existantes** dans notre manifeste d’application Teams. Elles ne s’appliquent qu’à l’intérieur de l’équipe/de la discussion où l’application est installée.
|
||||
Il s’agit des **autorisations resourceSpecific existantes** dans notre manifeste d’application Teams. Elles ne s’appliquent qu’au sein de l’équipe/chat où l’application est installée.
|
||||
|
||||
**Pour les canaux (étendue équipe) :**
|
||||
**Pour les canaux (portée équipe) :**
|
||||
|
||||
- `ChannelMessage.Read.Group` (Application) - recevoir tous les messages de canal sans @mention
|
||||
- `ChannelMessage.Send.Group` (Application)
|
||||
@ -328,9 +477,9 @@ Ce sont les **autorisations resourceSpecific existantes** dans notre manifeste d
|
||||
- `TeamMember.Read.Group` (Application)
|
||||
- `TeamSettings.Read.Group` (Application)
|
||||
|
||||
**Pour les discussions de groupe :**
|
||||
**Pour les conversations de groupe :**
|
||||
|
||||
- `ChatMessage.Read.Chat` (Application) - recevoir tous les messages de discussion de groupe sans @mention
|
||||
- `ChatMessage.Read.Chat` (Application) - recevoir tous les messages de conversation de groupe sans @mention
|
||||
|
||||
## Exemple de manifeste Teams (expurgé)
|
||||
|
||||
@ -382,15 +531,15 @@ Exemple minimal et valide avec les champs requis. Remplacez les ID et les URL.
|
||||
}
|
||||
```
|
||||
|
||||
### Réserves sur le manifeste (champs indispensables)
|
||||
### Réserves concernant le manifeste (champs indispensables)
|
||||
|
||||
- `bots[].botId` **doit** correspondre à l’Azure Bot App ID.
|
||||
- `webApplicationInfo.id` **doit** correspondre à l’Azure Bot App ID.
|
||||
- `bots[].botId` **doit** correspondre à l’ID d’application Azure Bot.
|
||||
- `webApplicationInfo.id` **doit** correspondre à l’ID d’application Azure Bot.
|
||||
- `bots[].scopes` doit inclure les surfaces que vous prévoyez d’utiliser (`personal`, `team`, `groupChat`).
|
||||
- `bots[].supportsFiles: true` est requis pour la gestion des fichiers dans l’étendue personnelle.
|
||||
- `authorization.permissions.resourceSpecific` doit inclure la lecture/l’envoi de canaux si vous voulez du trafic de canal.
|
||||
- `bots[].supportsFiles: true` est requis pour la gestion des fichiers dans la portée personnelle.
|
||||
- `authorization.permissions.resourceSpecific` doit inclure la lecture/l’envoi dans les canaux si vous voulez du trafic de canal.
|
||||
|
||||
### Mettre à jour une application existante
|
||||
### Mise à jour d’une application existante
|
||||
|
||||
Pour mettre à jour une application Teams déjà installée (par exemple, pour ajouter des autorisations RSC) :
|
||||
|
||||
@ -399,23 +548,23 @@ Pour mettre à jour une application Teams déjà installée (par exemple, pour a
|
||||
3. **Recompressez** le manifeste avec les icônes (`manifest.json`, `outline.png`, `color.png`)
|
||||
4. Téléversez le nouveau zip :
|
||||
- **Option A (Teams Admin Center) :** Teams Admin Center → Teams apps → Manage apps → trouvez votre application → Upload new version
|
||||
- **Option B (chargement latéral) :** Dans Teams → Apps → Manage your apps → Upload a custom app
|
||||
- **Option B (chargement latéral) :** dans Teams → Apps → Manage your apps → Upload a custom app
|
||||
5. **Pour les canaux d’équipe :** réinstallez l’application dans chaque équipe pour que les nouvelles autorisations prennent effet
|
||||
6. **Quittez complètement et relancez Teams** (pas seulement fermer la fenêtre) pour effacer les métadonnées d’application mises en cache
|
||||
6. **Quittez complètement et relancez Teams** (pas seulement fermer la fenêtre) pour vider les métadonnées d’application mises en cache
|
||||
|
||||
## Capacités : RSC uniquement vs Graph
|
||||
## Capacités : RSC seulement vs Graph
|
||||
|
||||
### Avec **Teams RSC uniquement** (application installée, sans autorisations API Graph)
|
||||
### Avec **Teams RSC seulement** (application installée, sans autorisations API Graph)
|
||||
|
||||
Fonctionne :
|
||||
|
||||
- Lire le contenu **texte** des messages de canal.
|
||||
- Envoyer le contenu **texte** des messages de canal.
|
||||
- Recevoir des pièces jointes de fichiers en **personnel (DM)**.
|
||||
- Envoyer du contenu **texte** dans les messages de canal.
|
||||
- Recevoir des pièces jointes de fichiers en **personnel (MP)**.
|
||||
|
||||
Ne fonctionne PAS :
|
||||
|
||||
- Le contenu **image ou fichier** des canaux/groupes (la charge utile n’inclut qu’un stub HTML).
|
||||
- Le contenu des **images ou fichiers** de canal/groupe (la charge utile n’inclut qu’un stub HTML).
|
||||
- Le téléchargement des pièces jointes stockées dans SharePoint/OneDrive.
|
||||
- La lecture de l’historique des messages (au-delà de l’événement webhook en direct).
|
||||
|
||||
@ -423,45 +572,45 @@ Ne fonctionne PAS :
|
||||
|
||||
Ajoute :
|
||||
|
||||
- Le téléchargement des contenus hébergés (images collées dans des messages).
|
||||
- Le téléchargement des contenus hébergés (images collées dans les messages).
|
||||
- Le téléchargement des pièces jointes de fichiers stockées dans SharePoint/OneDrive.
|
||||
- La lecture de l’historique des messages de canal/discussion via Graph.
|
||||
- La lecture de l’historique des messages de canal/chat via Graph.
|
||||
|
||||
### RSC vs API Graph
|
||||
|
||||
| Capacité | Autorisations RSC | API Graph |
|
||||
| ----------------------- | -------------------- | ----------------------------------- |
|
||||
| **Messages en temps réel** | Oui (via webhook) | Non (sondage uniquement) |
|
||||
| **Messages en temps réel** | Oui (via webhook) | Non (interrogation uniquement) |
|
||||
| **Messages historiques** | Non | Oui (peut interroger l’historique) |
|
||||
| **Complexité de configuration** | Manifeste d’application uniquement | Nécessite consentement administrateur + flux de jetons |
|
||||
| **Fonctionne hors ligne** | Non (doit être en cours d’exécution) | Oui (interroger à tout moment) |
|
||||
| **Complexité de configuration** | Manifeste d’application uniquement | Nécessite un consentement administrateur + un flux de jetons |
|
||||
| **Fonctionne hors ligne** | Non (doit être en cours d’exécution) | Oui (interrogeable à tout moment) |
|
||||
|
||||
**En résumé :** RSC sert à l’écoute en temps réel ; l’API Graph sert à l’accès historique. Pour rattraper les messages manqués hors ligne, vous avez besoin de l’API Graph avec `ChannelMessage.Read.All` (nécessite le consentement administrateur).
|
||||
**En résumé :** RSC sert à l’écoute en temps réel ; l’API Graph sert à l’accès historique. Pour récupérer les messages manqués pendant une indisponibilité, vous avez besoin de l’API Graph avec `ChannelMessage.Read.All` (nécessite un consentement administrateur).
|
||||
|
||||
## Médias + historique activés par Graph (requis pour les canaux)
|
||||
|
||||
Si vous avez besoin d’images/fichiers dans les **canaux** ou si vous voulez récupérer **l’historique des messages**, vous devez activer les autorisations Microsoft Graph et accorder le consentement administrateur.
|
||||
|
||||
1. Dans l’**App Registration** Entra ID (Azure AD), ajoutez des **autorisations d’application** Microsoft Graph :
|
||||
1. Dans l’**enregistrement d’application** Entra ID (Azure AD), ajoutez les **autorisations d’application** Microsoft Graph :
|
||||
- `ChannelMessage.Read.All` (pièces jointes de canal + historique)
|
||||
- `Chat.Read.All` ou `ChatMessage.Read.All` (discussions de groupe)
|
||||
- `Chat.Read.All` ou `ChatMessage.Read.All` (conversations de groupe)
|
||||
2. **Accordez le consentement administrateur** pour le locataire.
|
||||
3. Incrémentez la **version du manifeste** de l’application Teams, téléversez-la de nouveau, puis **réinstallez l’application dans Teams**.
|
||||
4. **Quittez complètement et relancez Teams** pour effacer les métadonnées d’application mises en cache.
|
||||
3. Incrémentez la **version du manifeste** de l’application Teams, téléversez-la à nouveau, puis **réinstallez l’application dans Teams**.
|
||||
4. **Quittez complètement et relancez Teams** pour vider les métadonnées d’application mises en cache.
|
||||
|
||||
**Autorisation supplémentaire pour les mentions utilisateur :** les @mentions utilisateur fonctionnent immédiatement pour les utilisateurs présents dans la conversation. En revanche, si vous voulez rechercher dynamiquement et mentionner des utilisateurs qui **ne sont pas dans la conversation actuelle**, ajoutez l’autorisation `User.Read.All` (Application) et accordez le consentement administrateur.
|
||||
**Autorisation supplémentaire pour les mentions d’utilisateurs :** les @mentions d’utilisateurs fonctionnent prêtes à l’emploi pour les utilisateurs dans la conversation. Toutefois, si vous voulez rechercher dynamiquement et mentionner des utilisateurs qui **ne sont pas dans la conversation actuelle**, ajoutez l’autorisation d’application `User.Read.All` et accordez le consentement administrateur.
|
||||
|
||||
## Limitations connues
|
||||
|
||||
### Délais d’attente des webhooks
|
||||
### Délais d’expiration du webhook
|
||||
|
||||
Teams transmet les messages via un webhook HTTP. Si le traitement prend trop de temps (par ex. réponses LLM lentes), vous pouvez voir :
|
||||
Teams distribue les messages via un webhook HTTP. Si le traitement prend trop de temps (par ex. réponses LLM lentes), vous pouvez voir :
|
||||
|
||||
- Des délais d’attente gateway
|
||||
- Des nouvelles tentatives Teams sur le message (provoquant des doublons)
|
||||
- Des réponses perdues
|
||||
- Délais d’expiration de la passerelle
|
||||
- Nouveaux essais du message par Teams (provoquant des doublons)
|
||||
- Réponses perdues
|
||||
|
||||
OpenClaw gère cela en renvoyant rapidement puis en envoyant les réponses de manière proactive, mais des réponses très lentes peuvent toujours poser problème.
|
||||
OpenClaw gère cela en répondant rapidement puis en envoyant les réponses de manière proactive, mais des réponses très lentes peuvent tout de même poser problème.
|
||||
|
||||
### Mise en forme
|
||||
|
||||
@ -469,41 +618,46 @@ Le markdown Teams est plus limité que celui de Slack ou Discord :
|
||||
|
||||
- La mise en forme de base fonctionne : **gras**, _italique_, `code`, liens
|
||||
- Le markdown complexe (tableaux, listes imbriquées) peut ne pas être rendu correctement
|
||||
- Les Adaptive Cards sont prises en charge pour les sondages et les envois arbitraires de cartes (voir ci-dessous)
|
||||
- Les cartes adaptatives sont prises en charge pour les sondages et les envois arbitraires de cartes (voir ci-dessous)
|
||||
|
||||
## Configuration
|
||||
|
||||
Paramètres clés (voir `/gateway/configuration` pour les modèles de canal partagés) :
|
||||
Paramètres clés (voir `/gateway/configuration` pour les modèles de canaux partagés) :
|
||||
|
||||
- `channels.msteams.enabled` : activer/désactiver le canal.
|
||||
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId` : identifiants du bot.
|
||||
- `channels.msteams.webhook.port` (par défaut `3978`)
|
||||
- `channels.msteams.webhook.path` (par défaut `/api/messages`)
|
||||
- `channels.msteams.dmPolicy` : `pairing | allowlist | open | disabled` (par défaut : pairing)
|
||||
- `channels.msteams.allowFrom` : liste d’autorisation DM (ID d’objet AAD recommandés). L’assistant résout les noms en ID pendant la configuration lorsque l’accès Graph est disponible.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching` : interrupteur de secours pour réactiver la correspondance sur UPN/nom d’affichage modifiables et le routage direct par nom d’équipe/canal.
|
||||
- `channels.msteams.textChunkLimit` : taille des blocs de texte sortants.
|
||||
- `channels.msteams.allowFrom` : liste d’autorisation des MP (ID d’objet AAD recommandés). L’assistant résout les noms en ID pendant la configuration lorsque l’accès Graph est disponible.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching` : option de secours d’urgence pour réactiver la correspondance avec des UPN/noms d’affichage modifiables et le routage direct par nom d’équipe/canal.
|
||||
- `channels.msteams.textChunkLimit` : taille des segments de texte sortants.
|
||||
- `channels.msteams.chunkMode` : `length` (par défaut) ou `newline` pour découper sur les lignes vides (limites de paragraphe) avant le découpage par longueur.
|
||||
- `channels.msteams.mediaAllowHosts` : liste d’autorisation des hôtes pour les pièces jointes entrantes (par défaut, domaines Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts` : liste d’autorisation pour joindre des en-têtes Authorization lors des nouvelles tentatives sur des médias (par défaut, hôtes Graph + Bot Framework).
|
||||
- `channels.msteams.requireMention` : exiger une @mention dans les canaux/groupes (true par défaut).
|
||||
- `channels.msteams.replyStyle` : `thread | top-level` (voir [Reply Style](#reply-style-threads-vs-posts)).
|
||||
- `channels.msteams.mediaAllowHosts` : liste d’autorisation des hôtes pour les pièces jointes entrantes (par défaut domaines Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts` : liste d’autorisation pour joindre des en-têtes Authorization lors des nouvelles tentatives sur les médias (par défaut hôtes Graph + Bot Framework).
|
||||
- `channels.msteams.requireMention` : exiger une @mention dans les canaux/groupes (par défaut true).
|
||||
- `channels.msteams.replyStyle` : `thread | top-level` (voir [Style de réponse](#reply-style-threads-vs-posts)).
|
||||
- `channels.msteams.teams.<teamId>.replyStyle` : remplacement par équipe.
|
||||
- `channels.msteams.teams.<teamId>.requireMention` : remplacement par équipe.
|
||||
- `channels.msteams.teams.<teamId>.tools` : remplacements de politique d’outils par défaut par équipe (`allow`/`deny`/`alsoAllow`) utilisés lorsqu’un remplacement de canal est absent.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender` : remplacements de politique d’outils par équipe et par expéditeur (`"*"` pris en charge).
|
||||
- `channels.msteams.teams.<teamId>.tools` : remplacements de stratégie d’outils par défaut par équipe (`allow`/`deny`/`alsoAllow`) utilisés lorsqu’un remplacement de canal est absent.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender` : remplacements de stratégie d’outils par défaut par équipe et par expéditeur (joker `"*"` pris en charge).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle` : remplacement par canal.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention` : remplacement par canal.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools` : remplacements de politique d’outils par canal (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender` : remplacements de politique d’outils par canal et par expéditeur (`"*"` pris en charge).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools` : remplacements de stratégie d’outils par canal (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender` : remplacements de stratégie d’outils par canal et par expéditeur (joker `"*"` pris en charge).
|
||||
- Les clés `toolsBySender` doivent utiliser des préfixes explicites :
|
||||
`id:`, `e164:`, `username:`, `name:` (les anciennes clés sans préfixe sont toujours mappées uniquement à `id:`).
|
||||
- `channels.msteams.actions.memberInfo` : activer ou désactiver l’action d’informations sur les membres reposant sur Graph (activée par défaut lorsque les identifiants Graph sont disponibles).
|
||||
- `channels.msteams.sharePointSiteId` : ID du site SharePoint pour les téléversements de fichiers dans les discussions/canaux de groupe (voir [Sending files in group chats](#sending-files-in-group-chats)).
|
||||
`id:`, `e164:`, `username:`, `name:` (les anciennes clés sans préfixe sont toujours mappées uniquement vers `id:`).
|
||||
- `channels.msteams.actions.memberInfo` : activer ou désactiver l’action d’informations sur le membre adossée à Graph (par défaut : activée lorsque des identifiants Graph sont disponibles).
|
||||
- `channels.msteams.authType` : type d’authentification — `"secret"` (par défaut) ou `"federated"`.
|
||||
- `channels.msteams.certificatePath` : chemin vers le fichier de certificat PEM (fédéré + authentification par certificat).
|
||||
- `channels.msteams.certificateThumbprint` : empreinte du certificat (facultatif, non requis pour l’authentification).
|
||||
- `channels.msteams.useManagedIdentity` : activer l’authentification par identité managée (mode fédéré).
|
||||
- `channels.msteams.managedIdentityClientId` : ID client pour l’identité managée attribuée par l’utilisateur.
|
||||
- `channels.msteams.sharePointSiteId` : ID du site SharePoint pour les téléversements de fichiers dans les conversations de groupe/canaux (voir [Envoi de fichiers dans les conversations de groupe](#sending-files-in-group-chats)).
|
||||
|
||||
## Routage et sessions
|
||||
|
||||
- Les clés de session suivent le format d’agent standard (voir [/concepts/session](/concepts/session)) :
|
||||
- Les clés de session suivent le format d’agent standard (voir [/concepts/session](/fr/concepts/session)) :
|
||||
- Les messages directs partagent la session principale (`agent:<agentId>:<mainKey>`).
|
||||
- Les messages de canal/groupe utilisent l’ID de conversation :
|
||||
- `agent:<agentId>:msteams:channel:<conversationId>`
|
||||
@ -515,15 +669,15 @@ Teams a récemment introduit deux styles d’interface de canal sur le même mod
|
||||
|
||||
| Style | Description | `replyStyle` recommandé |
|
||||
| ------------------------ | --------------------------------------------------------- | ----------------------- |
|
||||
| **Posts** (classique) | Les messages apparaissent comme des cartes avec des réponses en fil dessous | `thread` (par défaut) |
|
||||
| **Threads** (type Slack) | Les messages s’enchaînent linéairement, davantage comme Slack | `top-level` |
|
||||
| **Posts** (classique) | Les messages apparaissent comme des cartes avec des réponses en fil en dessous | `thread` (par défaut) |
|
||||
| **Threads** (type Slack) | Les messages s’affichent de façon linéaire, davantage comme dans Slack | `top-level` |
|
||||
|
||||
**Le problème :** l’API Teams n’expose pas le style d’interface utilisé par un canal. Si vous utilisez le mauvais `replyStyle` :
|
||||
|
||||
- `thread` dans un canal de style Threads → les réponses apparaissent imbriquées de manière maladroite
|
||||
- `top-level` dans un canal de style Posts → les réponses apparaissent comme des publications de niveau supérieur séparées au lieu d’être dans le fil
|
||||
- `thread` dans un canal de style Threads → les réponses apparaissent imbriquées de façon maladroite
|
||||
- `top-level` dans un canal de style Posts → les réponses apparaissent comme des publications distinctes de niveau supérieur au lieu d’être dans le fil
|
||||
|
||||
**Solution :** configurez `replyStyle` par canal en fonction de la manière dont le canal est configuré :
|
||||
**Solution :** configurez `replyStyle` par canal selon la configuration du canal :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -548,31 +702,31 @@ Teams a récemment introduit deux styles d’interface de canal sur le même mod
|
||||
|
||||
**Limitations actuelles :**
|
||||
|
||||
- **DM :** les images et pièces jointes de fichiers fonctionnent via les API de fichiers du bot Teams.
|
||||
- **Canaux/groupes :** les pièces jointes résident dans le stockage M365 (SharePoint/OneDrive). La charge utile webhook n’inclut qu’un stub HTML, pas les octets réels du fichier. **Les autorisations API Graph sont requises** pour télécharger les pièces jointes de canal.
|
||||
- Pour les envois explicites centrés sur les fichiers, utilisez `action=upload-file` avec `media` / `filePath` / `path` ; `message` facultatif devient le texte/commentaire d’accompagnement, et `filename` remplace le nom téléversé.
|
||||
- **MP :** les images et pièces jointes de fichiers fonctionnent via les API de fichiers du bot Teams.
|
||||
- **Canaux/groupes :** les pièces jointes résident dans le stockage M365 (SharePoint/OneDrive). La charge utile du webhook n’inclut qu’un stub HTML, pas les octets réels du fichier. **Les autorisations API Graph sont requises** pour télécharger les pièces jointes de canal.
|
||||
- Pour les envois explicites d’abord centrés sur les fichiers, utilisez `action=upload-file` avec `media` / `filePath` / `path` ; `message` facultatif devient le texte/commentaire d’accompagnement, et `filename` remplace le nom téléversé.
|
||||
|
||||
Sans autorisations Graph, les messages de canal avec images seront reçus en texte seul (le contenu de l’image n’est pas accessible au bot).
|
||||
Par défaut, OpenClaw ne télécharge les médias qu’à partir de noms d’hôte Microsoft/Teams. Remplacez ce comportement avec `channels.msteams.mediaAllowHosts` (utilisez `["*"]` pour autoriser n’importe quel hôte).
|
||||
Les en-têtes Authorization ne sont joints que pour les hôtes dans `channels.msteams.mediaAuthAllowHosts` (par défaut, hôtes Graph + Bot Framework). Gardez cette liste stricte (évitez les suffixes multi-locataires).
|
||||
Sans autorisations Graph, les messages de canal avec images seront reçus comme du texte uniquement (le contenu de l’image n’est pas accessible au bot).
|
||||
Par défaut, OpenClaw ne télécharge les médias que depuis les noms d’hôte Microsoft/Teams. Remplacez cela avec `channels.msteams.mediaAllowHosts` (utilisez `["*"]` pour autoriser n’importe quel hôte).
|
||||
Les en-têtes Authorization ne sont joints que pour les hôtes dans `channels.msteams.mediaAuthAllowHosts` (par défaut hôtes Graph + Bot Framework). Gardez cette liste stricte (évitez les suffixes multilocataires).
|
||||
|
||||
## Sending files in group chats
|
||||
## Envoi de fichiers dans les conversations de groupe
|
||||
|
||||
Les bots peuvent envoyer des fichiers dans les DM en utilisant le flux FileConsentCard (intégré). En revanche, **l’envoi de fichiers dans les discussions/canaux de groupe** nécessite une configuration supplémentaire :
|
||||
Les bots peuvent envoyer des fichiers dans les MP via le flux FileConsentCard (intégré). Cependant, **l’envoi de fichiers dans les conversations de groupe/canaux** nécessite une configuration supplémentaire :
|
||||
|
||||
| Contexte | Mode d’envoi des fichiers | Configuration requise |
|
||||
| ------------------------ | ------------------------------------------ | -------------------------------------------------- |
|
||||
| **DM** | FileConsentCard → l’utilisateur accepte → le bot téléverse | Fonctionne immédiatement |
|
||||
| **Discussions/canaux de groupe** | Téléversement vers SharePoint → lien de partage | Nécessite `sharePointSiteId` + autorisations Graph |
|
||||
| **Images (tout contexte)** | Inline encodé en Base64 | Fonctionne immédiatement |
|
||||
| Contexte | Méthode d’envoi des fichiers | Configuration requise |
|
||||
| ------------------------ | ------------------------------------------- | -------------------------------------------------- |
|
||||
| **MP** | FileConsentCard → l’utilisateur accepte → le bot téléverse | Fonctionne immédiatement |
|
||||
| **Conversations de groupe/canaux** | Téléversement vers SharePoint → lien de partage | Nécessite `sharePointSiteId` + autorisations Graph |
|
||||
| **Images (tout contexte)** | Inline encodé en Base64 | Fonctionne immédiatement |
|
||||
|
||||
### Pourquoi les discussions de groupe ont besoin de SharePoint
|
||||
### Pourquoi les conversations de groupe ont besoin de SharePoint
|
||||
|
||||
Les bots n’ont pas de lecteur OneDrive personnel (le point de terminaison API Graph `/me/drive` ne fonctionne pas pour les identités d’application). Pour envoyer des fichiers dans des discussions/canaux de groupe, le bot téléverse vers un **site SharePoint** et crée un lien de partage.
|
||||
Les bots n’ont pas de lecteur OneDrive personnel (le point de terminaison API Graph `/me/drive` ne fonctionne pas pour les identités d’application). Pour envoyer des fichiers dans les conversations de groupe/canaux, le bot téléverse vers un **site SharePoint** et crée un lien de partage.
|
||||
|
||||
### Configuration
|
||||
|
||||
1. **Ajoutez des autorisations API Graph** dans Entra ID (Azure AD) → App Registration :
|
||||
1. **Ajoutez les autorisations API Graph** dans Entra ID (Azure AD) → Enregistrement d’application :
|
||||
- `Sites.ReadWrite.All` (Application) - téléverser des fichiers vers SharePoint
|
||||
- `Chat.Read.All` (Application) - facultatif, active les liens de partage par utilisateur
|
||||
|
||||
@ -605,42 +759,42 @@ Les bots n’ont pas de lecteur OneDrive personnel (le point de terminaison API
|
||||
}
|
||||
```
|
||||
|
||||
### Comportement de partage
|
||||
### Comportement du partage
|
||||
|
||||
| Autorisation | Comportement de partage |
|
||||
| ----------------------------------------- | -------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` uniquement | Lien de partage à l’échelle de l’organisation (toute personne de l’organisation peut y accéder) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Lien de partage par utilisateur (seuls les membres de la discussion peuvent y accéder) |
|
||||
| Autorisation | Comportement du partage |
|
||||
| ---------------------------------------- | -------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` uniquement | Lien de partage à l’échelle de l’organisation (toute personne de l’organisation peut y accéder) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Lien de partage par utilisateur (seuls les membres du chat peuvent y accéder) |
|
||||
|
||||
Le partage par utilisateur est plus sûr, car seuls les participants à la discussion peuvent accéder au fichier. Si l’autorisation `Chat.Read.All` est absente, le bot revient à un partage à l’échelle de l’organisation.
|
||||
Le partage par utilisateur est plus sécurisé, car seuls les participants du chat peuvent accéder au fichier. Si l’autorisation `Chat.Read.All` est absente, le bot revient au partage à l’échelle de l’organisation.
|
||||
|
||||
### Comportement de repli
|
||||
|
||||
| Scénario | Résultat |
|
||||
| ------------------------------------------------- | -------------------------------------------------- |
|
||||
| Discussion de groupe + fichier + `sharePointSiteId` configuré | Téléverser vers SharePoint, envoyer le lien de partage |
|
||||
| Discussion de groupe + fichier + pas de `sharePointSiteId` | Tenter un téléversement OneDrive (peut échouer), envoyer uniquement du texte |
|
||||
| Discussion personnelle + fichier | Flux FileConsentCard (fonctionne sans SharePoint) |
|
||||
| Conversation de groupe + fichier + `sharePointSiteId` configuré | Téléversement vers SharePoint, envoi d’un lien de partage |
|
||||
| Conversation de groupe + fichier + pas de `sharePointSiteId` | Tentative de téléversement vers OneDrive (peut échouer), envoi du texte uniquement |
|
||||
| Conversation personnelle + fichier | Flux FileConsentCard (fonctionne sans SharePoint) |
|
||||
| Tout contexte + image | Inline encodé en Base64 (fonctionne sans SharePoint) |
|
||||
|
||||
### Emplacement de stockage des fichiers
|
||||
|
||||
Les fichiers téléversés sont stockés dans un dossier `/OpenClawShared/` de la bibliothèque de documents par défaut du site SharePoint configuré.
|
||||
|
||||
## Sondages (Adaptive Cards)
|
||||
## Sondages (cartes adaptatives)
|
||||
|
||||
OpenClaw envoie les sondages Teams sous forme d’Adaptive Cards (il n’existe pas d’API de sondage Teams native).
|
||||
OpenClaw envoie les sondages Teams sous forme de cartes adaptatives (il n’existe pas d’API de sondage Teams native).
|
||||
|
||||
- CLI : `openclaw message poll --channel msteams --target conversation:<id> ...`
|
||||
- Les votes sont enregistrés par la gateway dans `~/.openclaw/msteams-polls.json`.
|
||||
- La gateway doit rester en ligne pour enregistrer les votes.
|
||||
- Les votes sont enregistrés par la passerelle dans `~/.openclaw/msteams-polls.json`.
|
||||
- La passerelle doit rester en ligne pour enregistrer les votes.
|
||||
- Les sondages ne publient pas encore automatiquement de résumés de résultats (inspectez le fichier de stockage si nécessaire).
|
||||
|
||||
## Adaptive Cards (arbitraires)
|
||||
## Cartes adaptatives (arbitraires)
|
||||
|
||||
Envoyez n’importe quel JSON Adaptive Card à des utilisateurs ou conversations Teams à l’aide de l’outil `message` ou de la CLI.
|
||||
Envoyez n’importe quel JSON de carte adaptative à des utilisateurs ou conversations Teams à l’aide de l’outil `message` ou de la CLI.
|
||||
|
||||
Le paramètre `card` accepte un objet JSON Adaptive Card. Lorsque `card` est fourni, le texte du message est facultatif.
|
||||
Le paramètre `card` accepte un objet JSON de carte adaptative. Lorsque `card` est fourni, le texte du message est facultatif.
|
||||
|
||||
**Outil d’agent :**
|
||||
|
||||
@ -665,17 +819,17 @@ openclaw message send --channel msteams \
|
||||
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
|
||||
```
|
||||
|
||||
Consultez la [documentation Adaptive Cards](https://adaptivecards.io/) pour le schéma de carte et des exemples. Pour les détails du format cible, voir [Target formats](#target-formats) ci-dessous.
|
||||
Voir la [documentation sur les cartes adaptatives](https://adaptivecards.io/) pour le schéma des cartes et des exemples. Pour les détails sur le format des cibles, voir [Formats de cible](#target-formats) ci-dessous.
|
||||
|
||||
## Formats cibles
|
||||
## Formats de cible
|
||||
|
||||
Les cibles MSTeams utilisent des préfixes pour distinguer les utilisateurs des conversations :
|
||||
|
||||
| Type de cible | Format | Exemple |
|
||||
| ---------------------- | -------------------------------- | --------------------------------------------------- |
|
||||
| Utilisateur (par ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Utilisateur (par nom) | `user:<display-name>` | `user:John Smith` (nécessite l’API Graph) |
|
||||
| Groupe/canal | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Utilisateur (par nom) | `user:<display-name>` | `user:John Smith` (nécessite l’API Graph) |
|
||||
| Groupe/canal | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Groupe/canal (brut) | `<conversation-id>` | `19:abc123...@thread.tacv2` (si contient `@thread`) |
|
||||
|
||||
**Exemples CLI :**
|
||||
@ -687,15 +841,15 @@ openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "
|
||||
# Envoyer à un utilisateur par nom d’affichage (déclenche une recherche API Graph)
|
||||
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
|
||||
|
||||
# Envoyer à une discussion de groupe ou à un canal
|
||||
# Envoyer à une conversation de groupe ou à un canal
|
||||
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"
|
||||
|
||||
# Envoyer une Adaptive Card à une conversation
|
||||
# Envoyer une carte adaptative à une conversation
|
||||
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
|
||||
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'
|
||||
```
|
||||
|
||||
**Exemples d’outils d’agent :**
|
||||
**Exemples d’outil d’agent :**
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -719,23 +873,23 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread.
|
||||
}
|
||||
```
|
||||
|
||||
Remarque : sans le préfixe `user:`, les noms sont interprétés par défaut comme une résolution de groupe/équipe. Utilisez toujours `user:` lorsque vous ciblez des personnes par nom d’affichage.
|
||||
Remarque : sans le préfixe `user:`, les noms utilisent par défaut la résolution de groupe/équipe. Utilisez toujours `user:` lorsque vous ciblez des personnes par nom d’affichage.
|
||||
|
||||
## Messagerie proactive
|
||||
|
||||
- Les messages proactifs ne sont possibles **qu’après** une interaction d’un utilisateur, car nous stockons alors les références de conversation.
|
||||
- Voir `/gateway/configuration` pour `dmPolicy` et le filtrage par liste d’autorisation.
|
||||
- Les messages proactifs ne sont possibles **qu’après** qu’un utilisateur a interagi, car nous stockons alors les références de conversation.
|
||||
- Voir `/gateway/configuration` pour `dmPolicy` et le contrôle par liste d’autorisation.
|
||||
|
||||
## ID d’équipe et de canal (piège courant)
|
||||
## ID d’équipe et de canal (piège fréquent)
|
||||
|
||||
Le paramètre de requête `groupId` dans les URL Teams n’est **PAS** l’ID d’équipe utilisé pour la configuration. Extrayez plutôt les ID du chemin de l’URL :
|
||||
Le paramètre de requête `groupId` dans les URL Teams n’est **PAS** l’ID d’équipe utilisé pour la configuration. Extrayez plutôt les ID à partir du chemin de l’URL :
|
||||
|
||||
**URL d’équipe :**
|
||||
|
||||
```
|
||||
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
|
||||
└────────────────────────────┘
|
||||
ID d’équipe (décoder l’URL)
|
||||
ID d’équipe (décoder cette URL)
|
||||
```
|
||||
|
||||
**URL de canal :**
|
||||
@ -743,31 +897,31 @@ 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 de canal (décoder l’URL)
|
||||
ID de canal (décoder cette URL)
|
||||
```
|
||||
|
||||
**Pour la configuration :**
|
||||
|
||||
- ID d’équipe = segment de chemin après `/team/` (décodé de l’URL, par ex. `19:Bk4j...@thread.tacv2`)
|
||||
- ID de canal = segment de chemin après `/channel/` (décodé de l’URL)
|
||||
- ID d’équipe = segment de chemin après `/team/` (décodé depuis l’URL, par ex. `19:Bk4j...@thread.tacv2`)
|
||||
- ID de canal = segment de chemin après `/channel/` (décodé depuis l’URL)
|
||||
- **Ignorez** le paramètre de requête `groupId`
|
||||
|
||||
## Canaux privés
|
||||
|
||||
Les bots ont une prise en charge limitée dans les canaux privés :
|
||||
|
||||
| Fonctionnalité | Canaux standard | Canaux privés |
|
||||
| ---------------------------- | --------------- | --------------------- |
|
||||
| Installation du bot | Oui | Limitée |
|
||||
| Messages en temps réel (webhook) | Oui | Peut ne pas fonctionner |
|
||||
| Autorisations RSC | Oui | Peuvent se comporter différemment |
|
||||
| @mentions | Oui | Si le bot est accessible |
|
||||
| Historique API Graph | Oui | Oui (avec autorisations) |
|
||||
| Fonctionnalité | Canaux standard | Canaux privés |
|
||||
| ---------------------------- | ------------------ | ---------------------- |
|
||||
| Installation du bot | Oui | Limitée |
|
||||
| Messages en temps réel (webhook) | Oui | Peut ne pas fonctionner |
|
||||
| Autorisations RSC | Oui | Peut se comporter différemment |
|
||||
| @mentions | Oui | Si le bot est accessible |
|
||||
| Historique via API Graph | Oui | Oui (avec autorisations) |
|
||||
|
||||
**Solutions de contournement si les canaux privés ne fonctionnent pas :**
|
||||
|
||||
1. Utilisez des canaux standard pour les interactions avec le bot
|
||||
2. Utilisez les DM - les utilisateurs peuvent toujours envoyer directement un message au bot
|
||||
2. Utilisez les MP - les utilisateurs peuvent toujours envoyer directement un message au bot
|
||||
3. Utilisez l’API Graph pour l’accès historique (nécessite `ChannelMessage.Read.All`)
|
||||
|
||||
## Dépannage
|
||||
@ -776,37 +930,37 @@ Les bots ont une prise en charge limitée dans les canaux privés :
|
||||
|
||||
- **Les images ne s’affichent pas dans les canaux :** autorisations Graph ou consentement administrateur manquants. Réinstallez l’application Teams et quittez/rouvrez complètement Teams.
|
||||
- **Aucune réponse dans le canal :** les mentions sont requises par défaut ; définissez `channels.msteams.requireMention=false` ou configurez cela par équipe/canal.
|
||||
- **Incohérence de version (Teams affiche toujours l’ancien manifeste) :** supprimez puis réajoutez l’application et quittez complètement Teams pour actualiser.
|
||||
- **401 Unauthorized depuis le webhook :** attendu lors d’un test manuel sans JWT Azure - cela signifie que le point de terminaison est joignable mais que l’authentification a échoué. Utilisez Azure Web Chat pour tester correctement.
|
||||
- **Incompatibilité de version (Teams affiche toujours l’ancien manifeste) :** supprimez puis rajoutez l’application et quittez complètement Teams pour actualiser.
|
||||
- **401 Unauthorized depuis le webhook :** normal lors de tests manuels sans JWT Azure - cela signifie que le point de terminaison est joignable mais que l’authentification a échoué. Utilisez Azure Web Chat pour tester correctement.
|
||||
|
||||
### Erreurs de téléversement du manifeste
|
||||
|
||||
- **"Icon file cannot be empty" :** le manifeste référence des fichiers d’icône de 0 octet. Créez des icônes PNG valides (32x32 pour `outline.png`, 192x192 pour `color.png`).
|
||||
- **"webApplicationInfo.Id already in use" :** l’application est encore installée dans une autre équipe/discussion. Trouvez-la et désinstallez-la d’abord, ou attendez 5-10 minutes pour la propagation.
|
||||
- **"Something went wrong" lors du téléversement :** téléversez plutôt via [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), ouvrez les outils de développement du navigateur (F12) → onglet Network, puis vérifiez le corps de la réponse pour l’erreur réelle.
|
||||
- **"Icon file cannot be empty":** le manifeste référence des fichiers d’icône de 0 octet. Créez des icônes PNG valides (32x32 pour `outline.png`, 192x192 pour `color.png`).
|
||||
- **"webApplicationInfo.Id already in use":** l’application est encore installée dans une autre équipe/un autre chat. Trouvez-la et désinstallez-la d’abord, ou attendez 5 à 10 minutes pour la propagation.
|
||||
- **"Something went wrong" lors du téléversement :** téléversez plutôt via [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), ouvrez les DevTools du navigateur (F12) → onglet Network, puis vérifiez le corps de la réponse pour voir l’erreur réelle.
|
||||
- **Échec du chargement latéral :** essayez "Upload an app to your org's app catalog" au lieu de "Upload a custom app" - cela contourne souvent les restrictions de chargement latéral.
|
||||
|
||||
### Les autorisations RSC ne fonctionnent pas
|
||||
|
||||
1. Vérifiez que `webApplicationInfo.id` correspond exactement à l’App ID de votre bot
|
||||
2. Téléversez à nouveau l’application et réinstallez-la dans l’équipe/la discussion
|
||||
1. Vérifiez que `webApplicationInfo.id` correspond exactement à l’ID d’application de votre bot
|
||||
2. Téléversez de nouveau l’application et réinstallez-la dans l’équipe/le chat
|
||||
3. Vérifiez si l’administrateur de votre organisation a bloqué les autorisations RSC
|
||||
4. Confirmez que vous utilisez la bonne étendue : `ChannelMessage.Read.Group` pour les équipes, `ChatMessage.Read.Chat` pour les discussions de groupe
|
||||
4. Confirmez que vous utilisez la bonne portée : `ChannelMessage.Read.Group` pour les équipes, `ChatMessage.Read.Chat` pour les conversations de groupe
|
||||
|
||||
## Références
|
||||
|
||||
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - guide de configuration Azure Bot
|
||||
- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - créer/gérer des applications Teams
|
||||
- [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) - schéma du manifeste d’application Teams
|
||||
- [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) - recevoir les messages de canal avec RSC
|
||||
- [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) - référence des autorisations RSC
|
||||
- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (canal/groupe nécessite Graph)
|
||||
- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
- [Créer Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - guide de configuration Azure Bot
|
||||
- [Portail des développeurs Teams](https://dev.teams.microsoft.com/apps) - créer/gérer des applications Teams
|
||||
- [Schéma du manifeste d’application Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
|
||||
- [Recevoir les messages de canal avec RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
|
||||
- [Référence des autorisations RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
|
||||
- [Gestion des fichiers des bots Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (canal/groupe nécessite Graph)
|
||||
- [Messagerie proactive](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
|
||||
## Liens associés
|
||||
## Lié
|
||||
|
||||
- [Channels Overview](/channels) — tous les canaux pris en charge
|
||||
- [Pairing](/channels/pairing) — authentification DM et flux de pairing
|
||||
- [Groups](/channels/groups) — comportement des discussions de groupe et filtrage par mention
|
||||
- [Channel Routing](/channels/channel-routing) — routage de session pour les messages
|
||||
- [Security](/gateway/security) — modèle d’accès et durcissement
|
||||
- [Vue d’ensemble des canaux](/fr/channels) — tous les canaux pris en charge
|
||||
- [Pairing](/fr/channels/pairing) — authentification en MP et flux de pairing
|
||||
- [Groupes](/fr/channels/groups) — comportement des conversations de groupe et obligation de mention
|
||||
- [Routage des canaux](/fr/channels/channel-routing) — routage de session pour les messages
|
||||
- [Sécurité](/fr/gateway/security) — modèle d’accès et durcissement
|
||||
|
||||
@ -1,44 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous modifiez le runtime d’agent embarqué ou le registre de harness
|
||||
- Vous modifiez le runtime d’agent embarqué ou le registre de harnesss d’agent
|
||||
- Vous enregistrez un harness d’agent à partir d’un plugin intégré ou de confiance
|
||||
- Vous devez comprendre la relation entre le plugin Codex et les fournisseurs de modèles
|
||||
- Vous devez comprendre comment le plugin Codex est lié aux fournisseurs de modèles
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Surface SDK expérimentale pour les plugins qui remplacent l’exécuteur d’agent embarqué de bas niveau
|
||||
title: Plugins Agent Harness
|
||||
title: Plugins de harness d’agent
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:14Z"
|
||||
generated_at: "2026-04-12T00:18:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1
|
||||
source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Plugins Agent Harness
|
||||
# Plugins de harness d’agent
|
||||
|
||||
Un **agent harness** est l’exécuteur de bas niveau pour un tour préparé d’agent OpenClaw.
|
||||
Ce n’est ni un fournisseur de modèles, ni un canal, ni un registre d’outils.
|
||||
Un **harness d’agent** est l’exécuteur de bas niveau pour un tour préparé d’un agent OpenClaw. Ce n’est pas un fournisseur de modèles, ni un canal, ni un registre d’outils.
|
||||
|
||||
Utilisez cette surface uniquement pour des plugins natifs intégrés ou de confiance. Le contrat
|
||||
reste expérimental, car les types de paramètres reflètent volontairement l’exécuteur embarqué actuel.
|
||||
Utilisez cette surface uniquement pour les plugins natifs intégrés ou de confiance. Le contrat reste expérimental, car les types de paramètres reflètent intentionnellement le runner embarqué actuel.
|
||||
|
||||
## Quand utiliser un harness
|
||||
|
||||
Enregistrez un agent harness lorsqu’une famille de modèles possède son propre runtime de session natif
|
||||
et que le transport normal de fournisseur OpenClaw est une mauvaise abstraction.
|
||||
Enregistrez un harness d’agent lorsqu’une famille de modèles possède son propre runtime de session natif et que le transport de fournisseur OpenClaw normal est la mauvaise abstraction.
|
||||
|
||||
Exemples :
|
||||
|
||||
- un serveur natif d’agent de programmation qui gère lui-même les fils et la compaction
|
||||
- une CLI ou un daemon local qui doit diffuser en flux des événements natifs de plan/raisonnement/outils
|
||||
- un runtime de modèle qui nécessite son propre identifiant de reprise en plus de la
|
||||
transcription de session OpenClaw
|
||||
- un serveur d’agent de codage natif qui gère les threads et la compaction
|
||||
- une CLI ou un démon local qui doit diffuser des événements natifs de planification/raisonnement/outils
|
||||
- un runtime de modèle qui a besoin de son propre identifiant de reprise en plus de la transcription de session OpenClaw
|
||||
|
||||
N’enregistrez **pas** un harness simplement pour ajouter une nouvelle API LLM. Pour des API de modèles HTTP ou
|
||||
WebSocket normales, créez un [plugin fournisseur](/fr/plugins/sdk-provider-plugins).
|
||||
N’enregistrez **pas** un harness uniquement pour ajouter une nouvelle API LLM. Pour les API de modèles HTTP ou WebSocket normales, créez un [plugin de fournisseur](/fr/plugins/sdk-provider-plugins).
|
||||
|
||||
## Ce que le core continue de gérer
|
||||
## Ce que le cœur continue de gérer
|
||||
|
||||
Avant qu’un harness soit sélectionné, OpenClaw a déjà résolu :
|
||||
|
||||
@ -46,12 +41,11 @@ Avant qu’un harness soit sélectionné, OpenClaw a déjà résolu :
|
||||
- l’état d’authentification du runtime
|
||||
- le niveau de réflexion et le budget de contexte
|
||||
- le fichier de transcription/session OpenClaw
|
||||
- l’espace de travail, le bac à sable et la politique d’outils
|
||||
- les callbacks de réponse du canal et les callbacks de streaming
|
||||
- la politique de fallback de modèle et de changement de modèle actif
|
||||
- l’espace de travail, le bac à sable et la politique des outils
|
||||
- les callbacks de réponse du canal et les callbacks de diffusion en continu
|
||||
- la politique de repli du modèle et de bascule de modèle en direct
|
||||
|
||||
Cette séparation est intentionnelle. Un harness exécute une tentative préparée ; il ne choisit
|
||||
pas les fournisseurs, ne remplace pas la livraison des canaux et ne change pas silencieusement de modèle.
|
||||
Cette séparation est intentionnelle. Un harness exécute une tentative préparée ; il ne choisit pas les fournisseurs, ne remplace pas la distribution par canal et ne change pas silencieusement de modèle.
|
||||
|
||||
## Enregistrer un harness
|
||||
|
||||
@ -93,64 +87,49 @@ export default definePluginEntry({
|
||||
|
||||
OpenClaw choisit un harness après la résolution du fournisseur/modèle :
|
||||
|
||||
1. `OPENCLAW_AGENT_RUNTIME=<id>` force un harness enregistré avec cet id.
|
||||
1. `OPENCLAW_AGENT_RUNTIME=<id>` force un harness enregistré avec cet identifiant.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=pi` force le harness PI intégré.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` demande aux harness enregistrés s’ils prennent en charge le
|
||||
fournisseur/modèle résolu.
|
||||
4. Si aucun harness enregistré ne correspond, OpenClaw utilise PI, sauf si le fallback PI est
|
||||
désactivé.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` demande aux harness enregistrés s’ils prennent en charge le fournisseur/modèle résolu.
|
||||
4. Si aucun harness enregistré ne correspond, OpenClaw utilise PI sauf si le repli vers PI est désactivé.
|
||||
|
||||
Les échecs d’un harness de plugin forcé apparaissent comme des échecs d’exécution. En mode `auto`,
|
||||
OpenClaw peut revenir à PI lorsque le harness de plugin sélectionné échoue avant qu’un
|
||||
tour n’ait produit des effets de bord. Définissez `OPENCLAW_AGENT_HARNESS_FALLBACK=none` ou
|
||||
`embeddedHarness.fallback: "none"` pour faire de ce fallback un échec bloquant à la place.
|
||||
Les échecs d’un harness de plugin forcé apparaissent comme des échecs d’exécution. En mode `auto`, OpenClaw peut revenir à PI lorsque le harness de plugin sélectionné échoue avant qu’un tour ait produit des effets de bord. Définissez `OPENCLAW_AGENT_HARNESS_FALLBACK=none` ou `embeddedHarness.fallback: "none"` pour faire de ce repli un échec définitif à la place.
|
||||
|
||||
Le plugin Codex intégré enregistre `codex` comme identifiant de harness. Le core traite cela
|
||||
comme un identifiant ordinaire de harness de plugin ; les alias spécifiques à Codex doivent appartenir au plugin
|
||||
ou à la configuration de l’opérateur, pas au sélecteur de runtime partagé.
|
||||
Le plugin Codex intégré enregistre `codex` comme identifiant de harness. Le cœur traite cela comme un identifiant de harness de plugin ordinaire ; les alias spécifiques à Codex relèvent du plugin ou de la configuration de l’opérateur, pas du sélecteur de runtime partagé.
|
||||
|
||||
## Appairage fournisseur plus harness
|
||||
|
||||
La plupart des harness devraient également enregistrer un fournisseur. Le fournisseur rend visibles les références de modèle,
|
||||
l’état d’authentification, les métadonnées du modèle et la sélection `/model` au reste de
|
||||
OpenClaw. Le harness revendique ensuite ce fournisseur dans `supports(...)`.
|
||||
La plupart des harness devraient aussi enregistrer un fournisseur. Le fournisseur rend visibles au reste d’OpenClaw les références de modèle, l’état d’authentification, les métadonnées du modèle et la sélection `/model`. Le harness revendique ensuite ce fournisseur dans `supports(...)`.
|
||||
|
||||
Le plugin Codex intégré suit ce modèle :
|
||||
|
||||
- id du fournisseur : `codex`
|
||||
- références de modèle utilisateur : `codex/gpt-5.4`, `codex/gpt-5.2`, ou un autre modèle renvoyé
|
||||
par le serveur d’application Codex
|
||||
- id du harness : `codex`
|
||||
- auth : disponibilité synthétique du fournisseur, parce que le harness Codex gère lui-même la
|
||||
connexion/session Codex native
|
||||
- requête du serveur d’application : OpenClaw envoie l’identifiant nu du modèle à Codex et laisse le
|
||||
harness dialoguer avec le protocole natif du serveur d’application
|
||||
- identifiant du fournisseur : `codex`
|
||||
- références de modèle utilisateur : `codex/gpt-5.4`, `codex/gpt-5.2` ou un autre modèle renvoyé par le serveur d’application Codex
|
||||
- identifiant du harness : `codex`
|
||||
- authentification : disponibilité synthétique du fournisseur, parce que le harness Codex gère la connexion/session Codex native
|
||||
- requête app-server : OpenClaw envoie l’identifiant nu du modèle à Codex et laisse le harness parler au protocole app-server natif
|
||||
|
||||
Le plugin Codex est additif. Les références simples `openai/gpt-*` restent des références du fournisseur OpenAI
|
||||
et continuent d’utiliser le chemin normal du fournisseur OpenClaw. Sélectionnez `codex/gpt-*`
|
||||
lorsque vous voulez une auth gérée par Codex, la découverte des modèles Codex, des fils natifs, et une exécution via le
|
||||
serveur d’application Codex. `/model` peut basculer entre les modèles Codex renvoyés
|
||||
par le serveur d’application Codex sans nécessiter d’identifiants du fournisseur OpenAI.
|
||||
Le plugin Codex est additif. Les références simples `openai/gpt-*` restent des références du fournisseur OpenAI et continuent d’utiliser le chemin normal du fournisseur OpenClaw. Sélectionnez `codex/gpt-*` lorsque vous voulez une authentification gérée par Codex, la découverte des modèles Codex, des threads natifs et l’exécution via l’app-server Codex. `/model` peut basculer parmi les modèles Codex renvoyés par le serveur d’application Codex sans nécessiter d’identifiants du fournisseur OpenAI.
|
||||
|
||||
Pour la configuration opérateur, les exemples de préfixe de modèle et les configs réservées à Codex, voir
|
||||
[Codex Harness](/fr/plugins/codex-harness).
|
||||
Pour la configuration opérateur, les exemples de préfixes de modèle et les configurations propres à Codex, voir [Harness Codex](/fr/plugins/codex-harness).
|
||||
|
||||
OpenClaw exige la version `0.118.0` ou plus récente du serveur d’application Codex. Le plugin Codex vérifie
|
||||
la poignée de main d’initialisation du serveur d’application et bloque les serveurs plus anciens ou sans version afin que
|
||||
OpenClaw ne s’exécute que sur la surface de protocole avec laquelle il a été testé.
|
||||
OpenClaw exige Codex app-server `0.118.0` ou plus récent. Le plugin Codex vérifie la poignée de main d’initialisation de l’app-server et bloque les serveurs plus anciens ou sans version, afin qu’OpenClaw ne s’exécute que sur la surface de protocole avec laquelle il a été testé.
|
||||
|
||||
## Désactiver le fallback PI
|
||||
### Mode harness Codex natif
|
||||
|
||||
Par défaut, OpenClaw exécute les agents embarqués avec `agents.defaults.embeddedHarness`
|
||||
défini sur `{ runtime: "auto", fallback: "pi" }`. En mode `auto`, les harness de plugin enregistrés
|
||||
peuvent revendiquer une paire fournisseur/modèle. Si aucun ne correspond, ou si un harness de plugin sélectionné
|
||||
automatiquement échoue avant de produire une sortie, OpenClaw revient à PI.
|
||||
Le harness `codex` intégré est le mode Codex natif pour les tours d’agent OpenClaw embarqués. Activez d’abord le plugin `codex` intégré et incluez `codex` dans `plugins.allow` si votre configuration utilise une liste d’autorisation restrictive. Il est différent de `openai-codex/*` :
|
||||
|
||||
Définissez `fallback: "none"` lorsque vous devez prouver qu’un harness de plugin est le seul
|
||||
runtime exercé. Cela désactive le fallback automatique vers PI ; cela ne bloque pas
|
||||
un `runtime: "pi"` explicite ou `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
- `openai-codex/*` utilise l’OAuth ChatGPT/Codex via le chemin normal du fournisseur OpenClaw.
|
||||
- `codex/*` utilise le fournisseur Codex intégré et achemine le tour via Codex app-server.
|
||||
|
||||
Pour des exécutions embarquées réservées à Codex :
|
||||
Lorsque ce mode s’exécute, Codex gère l’identifiant natif du thread, le comportement de reprise, la compaction et l’exécution app-server. OpenClaw continue de gérer le canal de discussion, le miroir de transcription visible, la politique des outils, les approbations, la distribution des médias et la sélection de session. Utilisez `embeddedHarness.runtime: "codex"` avec `embeddedHarness.fallback: "none"` lorsque vous devez prouver que le chemin app-server Codex est utilisé et que le repli vers PI ne masque pas un harness natif défectueux.
|
||||
|
||||
## Désactiver le repli vers PI
|
||||
|
||||
Par défaut, OpenClaw exécute les agents embarqués avec `agents.defaults.embeddedHarness` défini sur `{ runtime: "auto", fallback: "pi" }`. En mode `auto`, les harness de plugin enregistrés peuvent revendiquer une paire fournisseur/modèle. Si aucun ne correspond, ou si un harness de plugin sélectionné automatiquement échoue avant de produire une sortie, OpenClaw revient à PI.
|
||||
|
||||
Définissez `fallback: "none"` lorsque vous devez prouver qu’un harness de plugin est le seul runtime exercé. Cela désactive le repli automatique vers PI ; cela ne bloque pas un `runtime: "pi"` explicite ni `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Pour des exécutions embarquées Codex uniquement :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -166,9 +145,7 @@ Pour des exécutions embarquées réservées à Codex :
|
||||
}
|
||||
```
|
||||
|
||||
Si vous voulez que n’importe quel harness de plugin enregistré puisse revendiquer les modèles correspondants, mais ne
|
||||
voulez jamais qu’OpenClaw revienne silencieusement à PI, conservez `runtime: "auto"` et désactivez
|
||||
le fallback :
|
||||
Si vous voulez que n’importe quel harness de plugin enregistré puisse revendiquer les modèles correspondants mais ne voulez jamais qu’OpenClaw revienne silencieusement à PI, conservez `runtime: "auto"` et désactivez le repli :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -208,9 +185,7 @@ Les remplacements par agent utilisent la même forme :
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` remplace toujours le runtime configuré. Utilisez
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` pour désactiver le fallback PI depuis
|
||||
l’environnement.
|
||||
`OPENCLAW_AGENT_RUNTIME` remplace toujours le runtime configuré. Utilisez `OPENCLAW_AGENT_HARNESS_FALLBACK=none` pour désactiver le repli vers PI depuis l’environnement.
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -218,53 +193,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Avec le fallback désactivé, une session échoue tôt lorsque le harness demandé n’est pas
|
||||
enregistré, ne prend pas en charge le fournisseur/modèle résolu, ou échoue avant d’avoir
|
||||
produit des effets de bord du tour. C’est intentionnel pour les déploiements réservés à Codex et
|
||||
pour les tests actifs qui doivent prouver que le chemin du serveur d’application Codex est réellement utilisé.
|
||||
Avec le repli désactivé, une session échoue tôt lorsque le harness demandé n’est pas enregistré, ne prend pas en charge le fournisseur/modèle résolu, ou échoue avant de produire des effets de bord du tour. C’est intentionnel pour les déploiements Codex uniquement et pour les tests en direct qui doivent prouver que le chemin app-server Codex est réellement utilisé.
|
||||
|
||||
Ce paramètre ne contrôle que le harness d’agent embarqué. Il ne désactive pas le routage de modèles spécifique au fournisseur pour
|
||||
les images, vidéos, musiques, TTS, PDF ou autres.
|
||||
Ce paramètre contrôle uniquement le harness d’agent embarqué. Il ne désactive pas le routage spécifique au fournisseur pour les images, vidéos, musique, TTS, PDF ou autres modèles.
|
||||
|
||||
## Sessions natives et miroir de transcription
|
||||
|
||||
Un harness peut conserver un identifiant de session native, un identifiant de fil, ou un jeton de reprise côté daemon.
|
||||
Conservez cette liaison explicitement associée à la session OpenClaw, et continuez à
|
||||
recopier la sortie assistant/outils visible par l’utilisateur dans la transcription OpenClaw.
|
||||
Un harness peut conserver un identifiant de session natif, un identifiant de thread ou un jeton de reprise côté démon. Gardez cette liaison explicitement associée à la session OpenClaw, et continuez à refléter dans la transcription OpenClaw la sortie de l’assistant/des outils visible par l’utilisateur.
|
||||
|
||||
La transcription OpenClaw reste la couche de compatibilité pour :
|
||||
|
||||
- l’historique de session visible par le canal
|
||||
- la recherche et l’indexation dans la transcription
|
||||
- l’historique de session visible dans le canal
|
||||
- la recherche et l’indexation de transcription
|
||||
- le retour au harness PI intégré lors d’un tour ultérieur
|
||||
- le comportement générique de `/new`, `/reset` et de suppression de session
|
||||
|
||||
Si votre harness stocke une liaison auxiliaire, implémentez `reset(...)` afin qu’OpenClaw puisse
|
||||
l’effacer lorsque la session OpenClaw propriétaire est réinitialisée.
|
||||
Si votre harness stocke une liaison auxiliaire, implémentez `reset(...)` afin qu’OpenClaw puisse l’effacer lorsque la session OpenClaw propriétaire est réinitialisée.
|
||||
|
||||
## Résultats d’outils et de médias
|
||||
## Résultats des outils et des médias
|
||||
|
||||
Le core construit la liste des outils OpenClaw et la transmet à la tentative préparée.
|
||||
Lorsqu’un harness exécute un appel d’outil dynamique, renvoyez le résultat de l’outil via
|
||||
la forme de résultat du harness au lieu d’envoyer vous-même les médias du canal.
|
||||
Le cœur construit la liste des outils OpenClaw et la transmet à la tentative préparée. Lorsqu’un harness exécute un appel d’outil dynamique, renvoyez le résultat de l’outil via la forme de résultat du harness au lieu d’envoyer vous-même les médias du canal.
|
||||
|
||||
Cela maintient les sorties de texte, image, vidéo, musique, TTS, approbation et outils de messagerie
|
||||
sur le même chemin de livraison que les exécutions adossées à PI.
|
||||
Cela maintient les sorties de texte, image, vidéo, musique, TTS, approbation et outils de messagerie sur le même chemin de distribution que les exécutions reposant sur PI.
|
||||
|
||||
## Limitations actuelles
|
||||
## Limites actuelles
|
||||
|
||||
- Le chemin d’importation public est générique, mais certains alias de types de tentative/résultat portent encore
|
||||
des noms `Pi` pour compatibilité.
|
||||
- L’installation de harness tiers est expérimentale. Préférez les plugins fournisseurs
|
||||
jusqu’à ce que vous ayez besoin d’un runtime de session natif.
|
||||
- Le changement de harness est pris en charge entre les tours. Ne changez pas de harness au
|
||||
milieu d’un tour après le début des outils natifs, des approbations, du texte d’assistant ou des
|
||||
envois de messages.
|
||||
- Le chemin d’importation public est générique, mais certains alias de type de tentative/résultat portent encore des noms `Pi` pour des raisons de compatibilité.
|
||||
- L’installation de harness tiers est expérimentale. Préférez les plugins de fournisseur jusqu’à ce que vous ayez besoin d’un runtime de session natif.
|
||||
- Le changement de harness est pris en charge d’un tour à l’autre. Ne changez pas de harness au milieu d’un tour après le démarrage d’outils natifs, d’approbations, de texte d’assistant ou d’envois de messages.
|
||||
|
||||
## Voir aussi
|
||||
## Liens associés
|
||||
|
||||
- [Aperçu du SDK](/fr/plugins/sdk-overview)
|
||||
- [Assistants runtime](/fr/plugins/sdk-runtime)
|
||||
- [Plugins fournisseurs](/fr/plugins/sdk-provider-plugins)
|
||||
- [Codex Harness](/fr/plugins/codex-harness)
|
||||
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview)
|
||||
- [Helpers de runtime](/fr/plugins/sdk-runtime)
|
||||
- [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins)
|
||||
- [Harness Codex](/fr/plugins/codex-harness)
|
||||
- [Fournisseurs de modèles](/fr/concepts/model-providers)
|
||||
|
||||
@ -1,32 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous voulez utiliser des modèles OpenAI dans OpenClaw
|
||||
- Vous voulez une authentification par abonnement Codex au lieu de clés API
|
||||
summary: Utiliser OpenAI via des clés API ou un abonnement Codex dans OpenClaw
|
||||
- Vous souhaitez utiliser des modèles OpenAI dans OpenClaw
|
||||
- Vous souhaitez utiliser l’authentification par abonnement Codex au lieu de clés API
|
||||
- Vous avez besoin d’un comportement d’exécution des agents GPT-5 plus strict
|
||||
summary: Utilisez OpenAI via des clés API ou un abonnement Codex dans OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T06:54:16Z"
|
||||
generated_at: "2026-04-12T00:18:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a2ce1ce5f085fe55ec50b8d20359180b9002c9730820cd5b0e011c3bf807b64
|
||||
source_hash: 7aa06fba9ac901e663685a6b26443a2f6aeb6ec3589d939522dc87cbb43497b4
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenAI
|
||||
|
||||
OpenAI fournit des API développeur pour les modèles GPT. Codex prend en charge **la connexion ChatGPT** pour un accès par abonnement
|
||||
ou **la connexion par clé API** pour un accès facturé à l'usage. Codex cloud exige une connexion ChatGPT.
|
||||
OpenAI prend explicitement en charge l'utilisation d'OAuth par abonnement dans des outils / flux de travail externes comme OpenClaw.
|
||||
OpenAI fournit des API développeur pour les modèles GPT. Codex prend en charge la **connexion ChatGPT** pour un accès par abonnement
|
||||
ou la connexion par **clé API** pour un accès facturé à l’usage. Codex cloud nécessite une connexion ChatGPT.
|
||||
OpenAI prend explicitement en charge l’utilisation d’OAuth d’abonnement dans des outils/workflows externes comme OpenClaw.
|
||||
|
||||
## Style d'interaction par défaut
|
||||
## Style d’interaction par défaut
|
||||
|
||||
OpenClaw peut ajouter une petite superposition de prompt spécifique à OpenAI pour les exécutions `openai/*` et
|
||||
`openai-codex/*`. Par défaut, cette superposition garde l'assistant chaleureux,
|
||||
collaboratif, concis, direct et un peu plus expressif sur le plan émotionnel,
|
||||
sans remplacer le prompt système de base d'OpenClaw. La superposition conviviale
|
||||
autorise aussi des emoji occasionnels lorsqu'ils s'intègrent naturellement, tout en gardant
|
||||
la sortie globale concise.
|
||||
OpenClaw peut ajouter une petite surcouche d’invite spécifique à OpenAI pour les exécutions `openai/*` et
|
||||
`openai-codex/*`. Par défaut, la surcouche garde l’assistant chaleureux,
|
||||
collaboratif, concis, direct et un peu plus expressif sur le plan émotionnel
|
||||
sans remplacer l’invite système de base d’OpenClaw. La surcouche conviviale
|
||||
autorise aussi l’emoji occasionnel lorsqu’il s’intègre naturellement, tout en gardant
|
||||
une sortie globale concise.
|
||||
|
||||
Clé de configuration :
|
||||
|
||||
@ -34,18 +35,18 @@ Clé de configuration :
|
||||
|
||||
Valeurs autorisées :
|
||||
|
||||
- `"friendly"` : valeur par défaut ; active la superposition spécifique à OpenAI.
|
||||
- `"friendly"` : valeur par défaut ; active la surcouche spécifique à OpenAI.
|
||||
- `"on"` : alias de `"friendly"`.
|
||||
- `"off"` : désactive la superposition et utilise uniquement le prompt de base d'OpenClaw.
|
||||
- `"off"` : désactive la surcouche et utilise uniquement l’invite de base d’OpenClaw.
|
||||
|
||||
Portée :
|
||||
|
||||
- S'applique aux modèles `openai/*`.
|
||||
- S'applique aux modèles `openai-codex/*`.
|
||||
- N'affecte pas les autres fournisseurs.
|
||||
- S’applique aux modèles `openai/*`.
|
||||
- S’applique aux modèles `openai-codex/*`.
|
||||
- N’affecte pas les autres fournisseurs.
|
||||
|
||||
Ce comportement est activé par défaut. Conservez explicitement `"friendly"` si vous voulez qu'il
|
||||
survive à de futures modifications locales de configuration :
|
||||
Ce comportement est activé par défaut. Conservez explicitement `"friendly"` si vous voulez que
|
||||
cela survive à de futurs changements de configuration locale :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -61,9 +62,9 @@ survive à de futures modifications locales de configuration :
|
||||
}
|
||||
```
|
||||
|
||||
### Désactiver la superposition de prompt OpenAI
|
||||
### Désactiver la surcouche d’invite OpenAI
|
||||
|
||||
Si vous voulez le prompt de base d'OpenClaw non modifié, définissez la superposition sur `"off"` :
|
||||
Si vous voulez l’invite de base OpenClaw non modifiée, définissez la surcouche sur `"off"` :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -79,31 +80,31 @@ Si vous voulez le prompt de base d'OpenClaw non modifié, définissez la superpo
|
||||
}
|
||||
```
|
||||
|
||||
Vous pouvez aussi le définir directement avec la CLI de configuration :
|
||||
Vous pouvez aussi la définir directement avec la CLI de configuration :
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.openai.config.personality off
|
||||
```
|
||||
|
||||
OpenClaw normalise ce paramètre sans tenir compte de la casse à l'exécution, donc des valeurs comme
|
||||
`"Off"` désactivent également la superposition conviviale.
|
||||
OpenClaw normalise ce paramètre sans tenir compte de la casse à l’exécution, donc des valeurs comme
|
||||
`"Off"` désactivent quand même la surcouche conviviale.
|
||||
|
||||
## Option A : clé API OpenAI (OpenAI Platform)
|
||||
|
||||
**Idéal pour :** accès API direct et facturation à l'usage.
|
||||
Récupérez votre clé API depuis le tableau de bord OpenAI.
|
||||
**Idéal pour :** l’accès direct à l’API et la facturation à l’usage.
|
||||
Obtenez votre clé API depuis le tableau de bord OpenAI.
|
||||
|
||||
Résumé des routes :
|
||||
Résumé du routage :
|
||||
|
||||
- `openai/gpt-5.4` = route API directe OpenAI Platform
|
||||
- Nécessite `OPENAI_API_KEY` (ou une configuration équivalente du fournisseur OpenAI)
|
||||
- Dans OpenClaw, la connexion ChatGPT/Codex passe par `openai-codex/*`, pas `openai/*`
|
||||
- Dans OpenClaw, la connexion ChatGPT/Codex passe par `openai-codex/*`, pas par `openai/*`
|
||||
|
||||
### Configuration via CLI
|
||||
### Configuration CLI
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
# ou en non interactif
|
||||
# ou en mode non interactif
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
@ -116,27 +117,28 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
}
|
||||
```
|
||||
|
||||
La documentation actuelle des modèles API d'OpenAI liste `gpt-5.4` et `gpt-5.4-pro` pour un usage API OpenAI direct. OpenClaw transmet les deux via le chemin `openai/*` Responses.
|
||||
OpenClaw masque volontairement l'entrée obsolète `openai/gpt-5.3-codex-spark`,
|
||||
car les appels API OpenAI directs la rejettent en trafic réel.
|
||||
La documentation actuelle des modèles API d’OpenAI liste `gpt-5.4` et `gpt-5.4-pro` pour une utilisation directe
|
||||
de l’API OpenAI. OpenClaw transmet les deux via le chemin Responses `openai/*`.
|
||||
OpenClaw masque intentionnellement l’entrée obsolète `openai/gpt-5.3-codex-spark`,
|
||||
car les appels directs à l’API OpenAI la rejettent dans le trafic réel.
|
||||
|
||||
OpenClaw **n'expose pas** `openai/gpt-5.3-codex-spark` sur le chemin API OpenAI direct.
|
||||
`pi-ai` livre toujours une entrée intégrée pour ce modèle, mais les requêtes API OpenAI réelles
|
||||
le rejettent actuellement. Spark est traité comme Codex uniquement dans OpenClaw.
|
||||
OpenClaw **n’expose pas** `openai/gpt-5.3-codex-spark` sur le chemin direct de l’API OpenAI.
|
||||
`pi-ai` inclut toujours une entrée intégrée pour ce modèle, mais les requêtes réelles à l’API OpenAI
|
||||
la rejettent actuellement. Spark est traité comme réservé à Codex dans OpenClaw.
|
||||
|
||||
## Génération d'images
|
||||
## Génération d’images
|
||||
|
||||
Le plugin groupé `openai` enregistre aussi la génération d'images via l'outil partagé
|
||||
Le plugin `openai` inclus enregistre aussi la génération d’images via l’outil partagé
|
||||
`image_generate`.
|
||||
|
||||
- Modèle d'image par défaut : `openai/gpt-image-1`
|
||||
- Génération : jusqu'à 4 images par requête
|
||||
- Mode édition : activé, jusqu'à 5 images de référence
|
||||
- Modèle d’image par défaut : `openai/gpt-image-1`
|
||||
- Génération : jusqu’à 4 images par requête
|
||||
- Mode édition : activé, jusqu’à 5 images de référence
|
||||
- Prend en charge `size`
|
||||
- Limitation actuelle spécifique à OpenAI : OpenClaw ne transmet pas aujourd'hui les surcharges `aspectRatio` ni
|
||||
`resolution` à l'API OpenAI Images
|
||||
- Limitation spécifique actuelle à OpenAI : OpenClaw ne transmet pas aujourd’hui les remplacements `aspectRatio` ou
|
||||
`resolution` à l’API OpenAI Images
|
||||
|
||||
Pour utiliser OpenAI comme fournisseur d'images par défaut :
|
||||
Pour utiliser OpenAI comme fournisseur d’images par défaut :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -150,21 +152,21 @@ Pour utiliser OpenAI comme fournisseur d'images par défaut :
|
||||
}
|
||||
```
|
||||
|
||||
Consultez [Image Generation](/fr/tools/image-generation) pour les paramètres
|
||||
de l'outil partagé, la sélection du fournisseur et le comportement de basculement.
|
||||
Voir [Image Generation](/fr/tools/image-generation) pour les paramètres
|
||||
de l’outil partagé, la sélection du fournisseur et le comportement de basculement.
|
||||
|
||||
## Génération de vidéo
|
||||
## Génération de vidéos
|
||||
|
||||
Le plugin groupé `openai` enregistre aussi la génération de vidéo via l'outil partagé
|
||||
Le plugin `openai` inclus enregistre aussi la génération de vidéos via l’outil partagé
|
||||
`video_generate`.
|
||||
|
||||
- Modèle vidéo par défaut : `openai/sora-2`
|
||||
- Modes : texte vers vidéo, image vers vidéo et flux de référence / édition à vidéo unique
|
||||
- Modes : texte vers vidéo, image vers vidéo, et flux de référence/édition à vidéo unique
|
||||
- Limites actuelles : 1 image ou 1 vidéo en entrée de référence
|
||||
- Limitation actuelle spécifique à OpenAI : OpenClaw ne transmet actuellement que les surcharges `size`
|
||||
pour la génération vidéo native OpenAI. Les surcharges facultatives non prises en charge
|
||||
telles que `aspectRatio`, `resolution`, `audio` et `watermark` sont ignorées
|
||||
et signalées sous forme d'avertissement d'outil.
|
||||
- Limitation spécifique actuelle à OpenAI : OpenClaw ne transmet actuellement que les remplacements
|
||||
`size` pour la génération vidéo native OpenAI. Les remplacements optionnels non pris en charge
|
||||
comme `aspectRatio`, `resolution`, `audio` et `watermark` sont ignorés
|
||||
et renvoyés sous forme d’avertissement d’outil.
|
||||
|
||||
Pour utiliser OpenAI comme fournisseur vidéo par défaut :
|
||||
|
||||
@ -180,24 +182,24 @@ Pour utiliser OpenAI comme fournisseur vidéo par défaut :
|
||||
}
|
||||
```
|
||||
|
||||
Consultez [Video Generation](/fr/tools/video-generation) pour les paramètres
|
||||
de l'outil partagé, la sélection du fournisseur et le comportement de basculement.
|
||||
Voir [Video Generation](/fr/tools/video-generation) pour les paramètres
|
||||
de l’outil partagé, la sélection du fournisseur et le comportement de basculement.
|
||||
|
||||
## Option B : abonnement OpenAI Code (Codex)
|
||||
|
||||
**Idéal pour :** utiliser l'accès par abonnement ChatGPT/Codex au lieu d'une clé API.
|
||||
Codex cloud exige une connexion ChatGPT, tandis que la CLI Codex prend en charge une connexion ChatGPT ou par clé API.
|
||||
**Idéal pour :** utiliser l’accès par abonnement ChatGPT/Codex au lieu d’une clé API.
|
||||
Codex cloud nécessite une connexion ChatGPT, tandis que la CLI Codex prend en charge la connexion par ChatGPT ou par clé API.
|
||||
|
||||
Résumé des routes :
|
||||
Résumé du routage :
|
||||
|
||||
- `openai-codex/gpt-5.4` = route OAuth ChatGPT/Codex
|
||||
- Utilise la connexion ChatGPT/Codex, pas une clé API directe OpenAI Platform
|
||||
- Les limites côté fournisseur pour `openai-codex/*` peuvent différer de l'expérience ChatGPT web / application
|
||||
- Les limites côté fournisseur pour `openai-codex/*` peuvent différer de l’expérience web/app ChatGPT
|
||||
|
||||
### Configuration via CLI (OAuth Codex)
|
||||
### Configuration CLI (OAuth Codex)
|
||||
|
||||
```bash
|
||||
# Exécuter OAuth Codex dans l'assistant
|
||||
# Exécuter OAuth Codex dans l’assistant
|
||||
openclaw onboard --auth-choice openai-codex
|
||||
|
||||
# Ou exécuter OAuth directement
|
||||
@ -212,44 +214,45 @@ openclaw models auth login --provider openai-codex
|
||||
}
|
||||
```
|
||||
|
||||
La documentation actuelle de Codex d'OpenAI liste `gpt-5.4` comme modèle Codex actuel. OpenClaw
|
||||
le mappe vers `openai-codex/gpt-5.4` pour l'utilisation OAuth ChatGPT/Codex.
|
||||
La documentation actuelle de Codex d’OpenAI liste `gpt-5.4` comme modèle Codex actuel. OpenClaw
|
||||
l’associe à `openai-codex/gpt-5.4` pour l’utilisation avec OAuth ChatGPT/Codex.
|
||||
|
||||
Cette route est volontairement séparée de `openai/gpt-5.4`. Si vous voulez le
|
||||
chemin API direct OpenAI Platform, utilisez `openai/*` avec une clé API. Si vous voulez
|
||||
Cette route est volontairement distincte de `openai/gpt-5.4`. Si vous voulez le
|
||||
chemin direct de l’API OpenAI Platform, utilisez `openai/*` avec une clé API. Si vous voulez
|
||||
la connexion ChatGPT/Codex, utilisez `openai-codex/*`.
|
||||
|
||||
Si l'onboarding réutilise une connexion Codex CLI existante, ces identifiants restent
|
||||
gérés par Codex CLI. À l'expiration, OpenClaw relit d'abord la source Codex externe
|
||||
et, lorsque le fournisseur peut les actualiser, réécrit l'identifiant actualisé
|
||||
dans le stockage Codex au lieu d'en prendre possession dans une copie séparée réservée à OpenClaw.
|
||||
Si l’onboarding réutilise une connexion existante de la CLI Codex, ces identifiants restent
|
||||
gérés par la CLI Codex. À l’expiration, OpenClaw relit d’abord la source Codex externe
|
||||
et, lorsque le fournisseur peut l’actualiser, écrit l’identifiant actualisé
|
||||
dans le stockage Codex au lieu d’en prendre le contrôle dans une copie séparée propre à OpenClaw.
|
||||
|
||||
Si votre compte Codex a droit à Codex Spark, OpenClaw prend aussi en charge :
|
||||
Si votre compte Codex donne droit à Codex Spark, OpenClaw prend aussi en charge :
|
||||
|
||||
- `openai-codex/gpt-5.3-codex-spark`
|
||||
|
||||
OpenClaw traite Codex Spark comme réservé à Codex. Il n'expose pas de chemin direct
|
||||
`openai/gpt-5.3-codex-spark` par clé API.
|
||||
OpenClaw traite Codex Spark comme réservé à Codex. Il n’expose pas de chemin direct
|
||||
`openai/gpt-5.3-codex-spark` avec clé API.
|
||||
|
||||
OpenClaw préserve aussi `openai-codex/gpt-5.3-codex-spark` lorsque `pi-ai`
|
||||
le découvre. Considérez-le comme dépendant des droits et expérimental : Codex Spark est
|
||||
distinct du `/fast` de GPT-5.4, et sa disponibilité dépend du compte Codex /
|
||||
OpenClaw conserve aussi `openai-codex/gpt-5.3-codex-spark` lorsque `pi-ai`
|
||||
le détecte. Considérez-le comme dépendant des droits et expérimental : Codex Spark est
|
||||
distinct de GPT-5.4 `/fast`, et sa disponibilité dépend du compte Codex /
|
||||
ChatGPT connecté.
|
||||
|
||||
### Limite de fenêtre de contexte Codex
|
||||
|
||||
OpenClaw traite les métadonnées du modèle Codex et la limite de contexte d'exécution comme des
|
||||
OpenClaw traite les métadonnées du modèle Codex et la limite de contexte à l’exécution comme des
|
||||
valeurs distinctes.
|
||||
|
||||
Pour `openai-codex/gpt-5.4` :
|
||||
|
||||
- `contextWindow` natif : `1050000`
|
||||
- limite par défaut de `contextTokens` à l'exécution : `272000`
|
||||
- plafond `contextTokens` par défaut à l’exécution : `272000`
|
||||
|
||||
Cela permet de garder des métadonnées de modèle fidèles tout en conservant la plus petite
|
||||
fenêtre d'exécution par défaut qui offre en pratique de meilleures caractéristiques de latence et de qualité.
|
||||
Cela permet de garder des métadonnées de modèle fidèles tout en conservant la
|
||||
fenêtre d’exécution par défaut plus petite, qui présente en pratique de meilleures caractéristiques
|
||||
de latence et de qualité.
|
||||
|
||||
Si vous voulez une limite effective différente, définissez `models.providers.<provider>.models[].contextTokens` :
|
||||
Si vous voulez un plafond effectif différent, définissez `models.providers.<provider>.models[].contextTokens` :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -268,49 +271,50 @@ Si vous voulez une limite effective différente, définissez `models.providers.<
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez `contextWindow` uniquement lorsque vous déclarez ou remplacez des métadonnées natives de modèle.
|
||||
Utilisez `contextTokens` lorsque vous voulez limiter le budget de contexte à l'exécution.
|
||||
Utilisez `contextWindow` uniquement lorsque vous déclarez ou remplacez des métadonnées natives
|
||||
du modèle. Utilisez `contextTokens` lorsque vous voulez limiter le budget de contexte à l’exécution.
|
||||
|
||||
### Transport par défaut
|
||||
|
||||
OpenClaw utilise `pi-ai` pour le streaming des modèles. Pour `openai/*` et
|
||||
`openai-codex/*`, le transport par défaut est `"auto"` (WebSocket d'abord, puis repli SSE).
|
||||
OpenClaw utilise `pi-ai` pour le streaming des modèles. Pour `openai/*` comme pour
|
||||
`openai-codex/*`, le transport par défaut est `"auto"` (WebSocket d’abord, puis repli sur SSE).
|
||||
|
||||
En mode `"auto"`, OpenClaw réessaie également un échec WebSocket précoce et réessayable
|
||||
avant de se rabattre sur SSE. Le mode forcé `"websocket"` expose toujours
|
||||
directement les erreurs de transport au lieu de les masquer derrière le repli.
|
||||
En mode `"auto"`, OpenClaw réessaie aussi une défaillance WebSocket précoce et récupérable
|
||||
avant de basculer sur SSE. Le mode forcé `"websocket"` continue d’exposer directement les erreurs de transport
|
||||
au lieu de les masquer derrière le repli.
|
||||
|
||||
Après un échec WebSocket à la connexion ou au début du tour en mode `"auto"`, OpenClaw marque
|
||||
Après un échec WebSocket à la connexion ou au début d’un tour en mode `"auto"`, OpenClaw marque
|
||||
le chemin WebSocket de cette session comme dégradé pendant environ 60 secondes et envoie
|
||||
les tours suivants via SSE pendant ce délai au lieu d'alterner inutilement entre
|
||||
les tours suivants via SSE pendant le temps de refroidissement au lieu d’osciller entre
|
||||
les transports.
|
||||
|
||||
Pour les points de terminaison natifs de la famille OpenAI (`openai/*`, `openai-codex/*` et Azure
|
||||
OpenAI Responses), OpenClaw attache aussi un état stable d'identité de session et de tour
|
||||
aux requêtes afin que les nouvelles tentatives, reconnexions et le repli SSE restent alignés sur la même
|
||||
identité de conversation. Sur les routes natives de la famille OpenAI, cela inclut des en-têtes stables
|
||||
d'identité de session / de tour ainsi que des métadonnées de transport correspondantes.
|
||||
Pour les endpoints natifs de la famille OpenAI (`openai/*`, `openai-codex/*` et Azure
|
||||
OpenAI Responses), OpenClaw attache aussi un état stable d’identité de session et de tour
|
||||
aux requêtes afin que les tentatives, reconnexions et replis SSE restent alignés sur la même
|
||||
identité de conversation. Sur les routes natives de la famille OpenAI, cela inclut des en-têtes
|
||||
stables d’identité de requête session/tour ainsi que des métadonnées de transport correspondantes.
|
||||
|
||||
OpenClaw normalise aussi les compteurs d'usage OpenAI entre variantes de transport avant
|
||||
qu'ils n'atteignent les surfaces de session / statut. Le trafic natif OpenAI / Codex Responses peut
|
||||
signaler l'usage soit sous `input_tokens` / `output_tokens`, soit sous
|
||||
`prompt_tokens` / `completion_tokens` ; OpenClaw les traite comme les mêmes compteurs d'entrée
|
||||
OpenClaw normalise aussi les compteurs d’usage OpenAI entre les variantes de transport avant
|
||||
qu’ils n’atteignent les surfaces de session/statut. Le trafic natif OpenAI/Codex Responses peut
|
||||
signaler l’usage soit comme `input_tokens` / `output_tokens`, soit comme
|
||||
`prompt_tokens` / `completion_tokens` ; OpenClaw les traite comme les mêmes compteurs d’entrée
|
||||
et de sortie pour `/status`, `/usage` et les journaux de session. Lorsque le trafic WebSocket natif
|
||||
omet `total_tokens` (ou signale `0`), OpenClaw se rabat sur le total normalisé entrée + sortie afin que les affichages de session / statut restent renseignés.
|
||||
omet `total_tokens` (ou signale `0`), OpenClaw revient au total normalisé entrée + sortie
|
||||
afin que les affichages de session/statut restent renseignés.
|
||||
|
||||
Vous pouvez définir `agents.defaults.models.<provider/model>.params.transport` :
|
||||
|
||||
- `"sse"` : forcer SSE
|
||||
- `"websocket"` : forcer WebSocket
|
||||
- `"auto"` : essayer WebSocket, puis se rabattre sur SSE
|
||||
- `"auto"` : essayer WebSocket, puis basculer sur SSE
|
||||
|
||||
Pour `openai/*` (API Responses), OpenClaw active aussi par défaut le préchauffage WebSocket
|
||||
Pour `openai/*` (API Responses), OpenClaw active aussi l’échauffement WebSocket par défaut
|
||||
(`openaiWsWarmup: true`) lorsque le transport WebSocket est utilisé.
|
||||
|
||||
Documentation OpenAI connexe :
|
||||
Documentation OpenAI associée :
|
||||
|
||||
- [API Realtime avec WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming des réponses API (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -329,12 +333,12 @@ Documentation OpenAI connexe :
|
||||
}
|
||||
```
|
||||
|
||||
### Préchauffage WebSocket OpenAI
|
||||
### Échauffement WebSocket OpenAI
|
||||
|
||||
La documentation OpenAI décrit le préchauffage comme facultatif. OpenClaw l'active par défaut pour
|
||||
`openai/*` afin de réduire la latence du premier tour lors de l'utilisation du transport WebSocket.
|
||||
La documentation OpenAI décrit l’échauffement comme facultatif. OpenClaw l’active par défaut pour
|
||||
`openai/*` afin de réduire la latence du premier tour lors de l’utilisation du transport WebSocket.
|
||||
|
||||
### Désactiver le préchauffage
|
||||
### Désactiver l’échauffement
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -352,7 +356,7 @@ La documentation OpenAI décrit le préchauffage comme facultatif. OpenClaw l'ac
|
||||
}
|
||||
```
|
||||
|
||||
### Activer explicitement le préchauffage
|
||||
### Activer explicitement l’échauffement
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -372,9 +376,9 @@ La documentation OpenAI décrit le préchauffage comme facultatif. OpenClaw l'ac
|
||||
|
||||
### Traitement prioritaire OpenAI et Codex
|
||||
|
||||
L'API d'OpenAI expose le traitement prioritaire via `service_tier=priority`. Dans
|
||||
L’API OpenAI expose le traitement prioritaire via `service_tier=priority`. Dans
|
||||
OpenClaw, définissez `agents.defaults.models["<provider>/<model>"].params.serviceTier`
|
||||
pour transmettre ce champ aux points de terminaison natifs OpenAI / Codex Responses.
|
||||
pour transmettre ce champ aux endpoints natifs OpenAI/Codex Responses.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -399,35 +403,35 @@ pour transmettre ce champ aux points de terminaison natifs OpenAI / Codex Respon
|
||||
|
||||
Les valeurs prises en charge sont `auto`, `default`, `flex` et `priority`.
|
||||
|
||||
OpenClaw transmet `params.serviceTier` à la fois aux requêtes directes `openai/*` Responses
|
||||
et aux requêtes `openai-codex/*` Codex Responses lorsque ces modèles pointent
|
||||
vers les points de terminaison natifs OpenAI / Codex.
|
||||
OpenClaw transmet `params.serviceTier` aux requêtes Responses directes `openai/*`
|
||||
et aux requêtes Codex Responses `openai-codex/*` lorsque ces modèles pointent
|
||||
vers les endpoints natifs OpenAI/Codex.
|
||||
|
||||
Comportement important :
|
||||
|
||||
- `openai/*` direct doit cibler `api.openai.com`
|
||||
- `openai-codex/*` doit cibler `chatgpt.com/backend-api`
|
||||
- si vous faites passer l'un ou l'autre fournisseur par une autre URL de base ou un proxy, OpenClaw laisse `service_tier` inchangé
|
||||
- si vous routez l’un ou l’autre fournisseur via une autre URL de base ou un proxy, OpenClaw laisse `service_tier` inchangé
|
||||
|
||||
### Mode rapide OpenAI
|
||||
|
||||
OpenClaw expose un basculement partagé de mode rapide pour les sessions `openai/*` et
|
||||
`openai-codex/*` :
|
||||
|
||||
- Discussion / UI : `/fast status|on|off`
|
||||
- Chat/UI : `/fast status|on|off`
|
||||
- Configuration : `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Lorsque le mode rapide est activé, OpenClaw le mappe au traitement prioritaire OpenAI :
|
||||
Lorsque le mode rapide est activé, OpenClaw l’associe au traitement prioritaire OpenAI :
|
||||
|
||||
- les appels directs `openai/*` Responses vers `api.openai.com` envoient `service_tier = "priority"`
|
||||
- les appels `openai-codex/*` Responses vers `chatgpt.com/backend-api` envoient aussi `service_tier = "priority"`
|
||||
- les valeurs `service_tier` déjà présentes dans la charge utile sont préservées
|
||||
- les valeurs `service_tier` déjà présentes dans la charge utile sont conservées
|
||||
- le mode rapide ne réécrit pas `reasoning` ni `text.verbosity`
|
||||
|
||||
Pour GPT 5.4 en particulier, la configuration la plus courante est :
|
||||
Pour GPT 5.4 en particulier, la configuration la plus courante est la suivante :
|
||||
|
||||
- envoyez `/fast on` dans une session utilisant `openai/gpt-5.4` ou `openai-codex/gpt-5.4`
|
||||
- ou définissez `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- envoyer `/fast on` dans une session utilisant `openai/gpt-5.4` ou `openai-codex/gpt-5.4`
|
||||
- ou définir `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- si vous utilisez aussi OAuth Codex, définissez également `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true`
|
||||
|
||||
Exemple :
|
||||
@ -453,46 +457,75 @@ Exemple :
|
||||
}
|
||||
```
|
||||
|
||||
Les surcharges de session priment sur la configuration. Effacer la surcharge de session dans l'UI Sessions
|
||||
ramène la session à la valeur par défaut configurée.
|
||||
Les remplacements au niveau de la session priment sur la configuration. Effacer le remplacement de session dans l’interface Sessions
|
||||
rétablit la valeur par défaut configurée pour la session.
|
||||
|
||||
### Routes natives OpenAI versus routes compatibles OpenAI
|
||||
|
||||
OpenClaw traite les points de terminaison directs OpenAI, Codex et Azure OpenAI différemment
|
||||
des proxys génériques compatibles OpenAI `/v1` :
|
||||
OpenClaw traite différemment les endpoints directs OpenAI, Codex et Azure OpenAI
|
||||
par rapport aux proxys génériques compatibles OpenAI `/v1` :
|
||||
|
||||
- les routes natives `openai/*`, `openai-codex/*` et Azure OpenAI conservent
|
||||
`reasoning: { effort: "none" }` intact lorsque vous désactivez explicitement le raisonnement
|
||||
- les routes natives de la famille OpenAI mettent par défaut les schémas d'outil en mode strict
|
||||
- les en-têtes cachés d'attribution OpenClaw (`originator`, `version` et
|
||||
`User-Agent`) ne sont attachés que sur les hôtes natifs OpenAI vérifiés
|
||||
- les routes natives de la famille OpenAI définissent par défaut les schémas d’outils en mode strict
|
||||
- les en-têtes d’attribution OpenClaw cachés (`originator`, `version` et
|
||||
`User-Agent`) ne sont ajoutés que sur les hôtes natifs OpenAI vérifiés
|
||||
(`api.openai.com`) et les hôtes natifs Codex (`chatgpt.com/backend-api`)
|
||||
- les routes natives OpenAI / Codex conservent la mise en forme de requête propre à OpenAI telle que
|
||||
`service_tier`, `store` pour Responses, les charges utiles de compatibilité de raisonnement OpenAI et
|
||||
les indications de cache de prompt
|
||||
- les routes de style proxy compatibles OpenAI conservent le comportement de compatibilité plus souple et
|
||||
ne forcent pas les schémas d'outil stricts, la mise en forme de requête réservée au natif ni les
|
||||
en-têtes cachés d'attribution OpenAI / Codex
|
||||
- les routes natives OpenAI/Codex conservent les ajustements de requête propres à OpenAI comme
|
||||
`service_tier`, `store` de Responses, les charges utiles de compatibilité de raisonnement OpenAI, et
|
||||
les indications de cache d’invite
|
||||
- les routes compatibles OpenAI de type proxy conservent le comportement de compatibilité plus souple et
|
||||
ne forcent pas les schémas d’outils stricts, les ajustements de requête réservés au natif, ni les en-têtes cachés
|
||||
d’attribution OpenAI/Codex
|
||||
|
||||
Azure OpenAI reste dans la catégorie de routage natif pour le transport et le comportement de compatibilité, mais il ne reçoit pas les en-têtes cachés d'attribution OpenAI / Codex.
|
||||
Azure OpenAI reste dans le groupe de routage natif pour le comportement de transport et de compatibilité,
|
||||
mais il ne reçoit pas les en-têtes cachés d’attribution OpenAI/Codex.
|
||||
|
||||
Cela préserve le comportement actuel natif OpenAI Responses sans imposer d'anciens
|
||||
shims compatibles OpenAI à des backends tiers `/v1`.
|
||||
Cela préserve le comportement actuel natif d’OpenAI Responses sans imposer d’anciens
|
||||
adaptateurs compatibles OpenAI à des backends `/v1` tiers.
|
||||
|
||||
### Compactage côté serveur OpenAI Responses
|
||||
### Mode GPT agentique strict
|
||||
|
||||
Pour les exécutions de la famille GPT-5 sur `openai/*` et `openai-codex/*`, OpenClaw peut utiliser un
|
||||
contrat d’exécution Pi intégré plus strict :
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
embeddedPi: {
|
||||
executionContract: "strict-agentic",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Avec `strict-agentic`, OpenClaw ne traite plus un tour d’assistant composé uniquement d’un plan comme
|
||||
une progression réussie lorsqu’une action d’outil concrète est disponible. Il réessaie le
|
||||
tour avec une directive d’action immédiate, active automatiquement l’outil structuré `update_plan` pour
|
||||
les travaux importants, et affiche un état de blocage explicite si le modèle continue
|
||||
à planifier sans agir.
|
||||
|
||||
Ce mode est limité aux exécutions de la famille GPT-5 d’OpenAI et OpenAI Codex. Les autres fournisseurs
|
||||
et les anciennes familles de modèles conservent le comportement Pi intégré par défaut, sauf si vous les faites
|
||||
opter pour d’autres paramètres d’exécution.
|
||||
|
||||
### Compaction côté serveur d’OpenAI Responses
|
||||
|
||||
Pour les modèles directs OpenAI Responses (`openai/*` utilisant `api: "openai-responses"` avec
|
||||
`baseUrl` sur `api.openai.com`), OpenClaw active désormais automatiquement les indications de charge utile de compactage côté serveur OpenAI :
|
||||
`baseUrl` sur `api.openai.com`), OpenClaw active désormais automatiquement les indications de charge utile
|
||||
de compaction côté serveur d’OpenAI :
|
||||
|
||||
- Force `store: true` (sauf si la compatibilité du modèle définit `supportsStore: false`)
|
||||
- Injecte `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
|
||||
Par défaut, `compact_threshold` vaut `70%` de `contextWindow` du modèle (ou `80000`
|
||||
lorsqu'il n'est pas disponible).
|
||||
Par défaut, `compact_threshold` vaut `70%` du `contextWindow` du modèle (ou `80000`
|
||||
s’il n’est pas disponible).
|
||||
|
||||
### Activer explicitement le compactage côté serveur
|
||||
### Activer explicitement la compaction côté serveur
|
||||
|
||||
Utilisez ceci lorsque vous voulez forcer l'injection de `context_management` sur des
|
||||
Utilisez ceci si vous voulez forcer l’injection de `context_management` sur des
|
||||
modèles Responses compatibles (par exemple Azure OpenAI Responses) :
|
||||
|
||||
```json5
|
||||
@ -530,7 +563,7 @@ modèles Responses compatibles (par exemple Azure OpenAI Responses) :
|
||||
}
|
||||
```
|
||||
|
||||
### Désactiver le compactage côté serveur
|
||||
### Désactiver la compaction côté serveur
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -548,11 +581,11 @@ modèles Responses compatibles (par exemple Azure OpenAI Responses) :
|
||||
}
|
||||
```
|
||||
|
||||
`responsesServerCompaction` ne contrôle que l'injection de `context_management`.
|
||||
Les modèles directs OpenAI Responses forcent toujours `store: true` sauf si la compatibilité définit
|
||||
`responsesServerCompaction` contrôle uniquement l’injection de `context_management`.
|
||||
Les modèles directs OpenAI Responses continuent à forcer `store: true` sauf si la compatibilité définit
|
||||
`supportsStore: false`.
|
||||
|
||||
## Remarques
|
||||
|
||||
- Les références de modèle utilisent toujours `provider/model` (voir [/concepts/models](/fr/concepts/models)).
|
||||
- Les détails d'authentification + les règles de réutilisation se trouvent dans [/concepts/oauth](/fr/concepts/oauth).
|
||||
- Les détails d’authentification et les règles de réutilisation se trouvent dans [/concepts/oauth](/fr/concepts/oauth).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user