chore(i18n): refresh pl translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
64b9245cf1
commit
4f18b4292c
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Praca nad funkcjami kanału Microsoft Teams
|
||||
summary: Stan obsługi, możliwości i konfiguracja bota Microsoft Teams
|
||||
summary: Stan obsługi bota Microsoft Teams, możliwości i konfiguracja
|
||||
title: Microsoft Teams
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:47:23Z"
|
||||
generated_at: "2026-04-12T00:18:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf
|
||||
source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79
|
||||
source_path: channels/msteams.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,15 +16,16 @@ x-i18n:
|
||||
|
||||
> „Porzućcie wszelką nadzieję, wy, którzy tu wchodzicie.”
|
||||
|
||||
Zaktualizowano: 2026-01-21
|
||||
Zaktualizowano: 2026-03-25
|
||||
|
||||
Stan: obsługiwane są tekst + załączniki DM; wysyłanie plików do kanałów/grup wymaga `sharePointSiteId` + uprawnień Graph (zobacz [Wysyłanie plików w czatach grupowych](#sending-files-in-group-chats)). Ankiety są wysyłane przez Adaptive Cards. Akcje wiadomości udostępniają jawne `upload-file` dla wysyłek rozpoczynających się od pliku.
|
||||
Stan: obsługiwane są tekst oraz załączniki DM; wysyłanie plików na kanałach/w grupach wymaga `sharePointSiteId` i uprawnień Graph (zobacz [Wysyłanie plików w czatach grupowych](#sending-files-in-group-chats)). Ankiety są wysyłane przez Adaptive Cards. Akcje wiadomości udostępniają jawne `upload-file` dla wysyłek rozpoczynających się od pliku.
|
||||
|
||||
## Bundled plugin
|
||||
|
||||
Microsoft Teams jest dostarczany jako bundled plugin w bieżących wydaniach OpenClaw, więc w standardowym spakowanym buildzie nie jest wymagana osobna instalacja.
|
||||
Microsoft Teams jest dostarczany jako bundled plugin w bieżących wydaniach OpenClaw, więc
|
||||
w standardowej paczkowanej kompilacji nie jest wymagana osobna instalacja.
|
||||
|
||||
Jeśli używasz starszego builda lub niestandardowej instalacji bez bundled Teams,
|
||||
Jeśli używasz starszej kompilacji lub niestandardowej instalacji bez dołączonego Teams,
|
||||
zainstaluj go ręcznie:
|
||||
|
||||
```bash
|
||||
@ -37,19 +38,19 @@ Lokalny checkout (podczas uruchamiania z repozytorium git):
|
||||
openclaw plugins install ./path/to/local/msteams-plugin
|
||||
```
|
||||
|
||||
Szczegóły: [Plugins](/tools/plugin)
|
||||
Szczegóły: [Plugins](/pl/tools/plugin)
|
||||
|
||||
## Szybka konfiguracja (dla początkujących)
|
||||
|
||||
1. Upewnij się, że plugin Microsoft Teams jest dostępny.
|
||||
- Bieżące spakowane wydania OpenClaw już go zawierają.
|
||||
- Bieżące paczkowane wydania OpenClaw zawierają go już domyślnie.
|
||||
- Starsze/niestandardowe instalacje mogą dodać go ręcznie za pomocą powyższych poleceń.
|
||||
2. Utwórz **Azure Bot** (App ID + client secret + tenant ID).
|
||||
3. Skonfiguruj OpenClaw przy użyciu tych poświadczeń.
|
||||
4. Udostępnij `/api/messages` (domyślnie port 3978) przez publiczny URL lub tunel.
|
||||
5. Zainstaluj pakiet aplikacji Teams i uruchom gateway.
|
||||
|
||||
Minimalna konfiguracja:
|
||||
Minimalna konfiguracja (client secret):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -65,19 +66,21 @@ Minimalna konfiguracja:
|
||||
}
|
||||
```
|
||||
|
||||
Uwaga: czaty grupowe są domyślnie blokowane (`channels.msteams.groupPolicy: "allowlist"`). Aby zezwolić na odpowiedzi w grupach, ustaw `channels.msteams.groupAllowFrom` (lub użyj `groupPolicy: "open"`, aby zezwolić każdemu członkowi, z bramkowaniem wzmianką).
|
||||
W środowiskach produkcyjnych rozważ użycie [uwierzytelniania federacyjnego](#federated-authentication-certificate--managed-identity) (certyfikat lub managed identity) zamiast client secret.
|
||||
|
||||
Uwaga: czaty grupowe są domyślnie blokowane (`channels.msteams.groupPolicy: "allowlist"`). Aby zezwolić na odpowiedzi w grupach, ustaw `channels.msteams.groupAllowFrom` (lub użyj `groupPolicy: "open"`, aby zezwolić dowolnemu członkowi, z bramkowaniem wzmianką).
|
||||
|
||||
## Cele
|
||||
|
||||
- Rozmawiać z OpenClaw przez DM-y Teams, czaty grupowe lub kanały.
|
||||
- Zachować deterministyczne routowanie: odpowiedzi zawsze wracają do kanału, z którego przyszły.
|
||||
- Domyślnie stosować bezpieczne zachowanie kanału (wzmianki wymagane, chyba że skonfigurowano inaczej).
|
||||
- Rozmawiaj z OpenClaw przez Teams DM, czaty grupowe lub kanały.
|
||||
- Zachowaj deterministyczny routing: odpowiedzi zawsze wracają do kanału, z którego przyszły.
|
||||
- Domyślnie stosuj bezpieczne zachowanie kanałów (wzmianki są wymagane, chyba że skonfigurowano inaczej).
|
||||
|
||||
## Zapisy konfiguracji
|
||||
|
||||
Domyślnie Microsoft Teams może zapisywać aktualizacje konfiguracji wywołane przez `/config set|unset` (wymaga `commands.config: true`).
|
||||
|
||||
Wyłącz przez:
|
||||
Wyłącz za pomocą:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -85,20 +88,20 @@ Wyłącz przez:
|
||||
}
|
||||
```
|
||||
|
||||
## Kontrola dostępu (DM-y + grupy)
|
||||
## Kontrola dostępu (DM + grupy)
|
||||
|
||||
**Dostęp DM**
|
||||
**Dostęp do DM**
|
||||
|
||||
- Domyślnie: `channels.msteams.dmPolicy = "pairing"`. Nieznani nadawcy są ignorowani do momentu zatwierdzenia.
|
||||
- Domyślnie: `channels.msteams.dmPolicy = "pairing"`. Nadawcy nieznani systemowi są ignorowani do momentu zatwierdzenia.
|
||||
- `channels.msteams.allowFrom` powinno używać stabilnych identyfikatorów obiektów AAD.
|
||||
- UPN-y/nazwy wyświetlane są zmienne; bezpośrednie dopasowanie jest domyślnie wyłączone i włączane tylko przez `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- Kreator może rozwiązywać nazwy na identyfikatory przez Microsoft Graph, jeśli poświadczenia na to pozwalają.
|
||||
- UPN-y/nazwy wyświetlane są zmienne; bezpośrednie dopasowywanie jest domyślnie wyłączone i włączane tylko przez `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- Kreator może rozwiązywać nazwy do identyfikatorów przez Microsoft Graph, jeśli poświadczenia na to pozwalają.
|
||||
|
||||
**Dostęp grupowy**
|
||||
**Dostęp do grup**
|
||||
|
||||
- Domyślnie: `channels.msteams.groupPolicy = "allowlist"` (zablokowane, dopóki nie dodasz `groupAllowFrom`). Użyj `channels.defaults.groupPolicy`, aby nadpisać wartość domyślną, gdy nie jest ustawiona.
|
||||
- `channels.msteams.groupAllowFrom` kontroluje, którzy nadawcy mogą wywoływać działanie w czatach grupowych/kanałach (zapasowo używa `channels.msteams.allowFrom`).
|
||||
- Ustaw `groupPolicy: "open"`, aby zezwolić każdemu członkowi (domyślnie nadal z bramkowaniem wzmianką).
|
||||
- Domyślnie: `channels.msteams.groupPolicy = "allowlist"` (zablokowane, dopóki nie dodasz `groupAllowFrom`). Użyj `channels.defaults.groupPolicy`, aby zastąpić domyślną wartość, gdy nie jest ustawiona.
|
||||
- `channels.msteams.groupAllowFrom` określa, którzy nadawcy mogą wyzwalać działania w czatach grupowych/kanałach (z fallbackiem do `channels.msteams.allowFrom`).
|
||||
- Ustaw `groupPolicy: "open"`, aby zezwolić dowolnemu członkowi (nadal z domyślnym bramkowaniem wzmianką).
|
||||
- Aby nie zezwalać na **żadne kanały**, ustaw `channels.msteams.groupPolicy: "disabled"`.
|
||||
|
||||
Przykład:
|
||||
@ -114,14 +117,14 @@ Przykład:
|
||||
}
|
||||
```
|
||||
|
||||
**Teams + allowlista kanałów**
|
||||
**Teams + lista dozwolonych kanałów**
|
||||
|
||||
- Ogranicz odpowiedzi w grupach/kanałach, podając zespoły i kanały w `channels.msteams.teams`.
|
||||
- Klucze powinny używać stabilnych identyfikatorów zespołów i identyfikatorów konwersacji kanałów.
|
||||
- Gdy `groupPolicy="allowlist"` i obecna jest allowlista zespołów, akceptowane są tylko wymienione zespoły/kanały (z bramkowaniem wzmianką).
|
||||
- Gdy `groupPolicy="allowlist"` i lista dozwolonych zespołów jest obecna, akceptowane są tylko wymienione zespoły/kanały (z bramkowaniem wzmianką).
|
||||
- Kreator konfiguracji akceptuje wpisy `Team/Channel` i zapisuje je za Ciebie.
|
||||
- Przy uruchamianiu OpenClaw rozwiązuje nazwy zespołów/kanałów i użytkowników z allowlisty na identyfikatory (gdy pozwalają na to uprawnienia Graph)
|
||||
i zapisuje mapowanie w logach; nierozwiązane nazwy zespołów/kanałów są zachowywane tak, jak zostały wpisane, ale domyślnie ignorowane przy routowaniu, chyba że włączono `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- Przy uruchomieniu OpenClaw rozwiązuje nazwy zespołów/kanałów oraz nazwy na liście dozwolonych użytkowników do identyfikatorów (gdy pozwalają na to uprawnienia Graph)
|
||||
i zapisuje mapowanie w logach; nierozwiązane nazwy zespołów/kanałów są zachowywane w podanej postaci, ale domyślnie ignorowane przy routingu, chyba że włączono `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
|
||||
Przykład:
|
||||
|
||||
@ -145,13 +148,13 @@ Przykład:
|
||||
## Jak to działa
|
||||
|
||||
1. Upewnij się, że plugin Microsoft Teams jest dostępny.
|
||||
- Bieżące spakowane wydania OpenClaw już go zawierają.
|
||||
- Bieżące paczkowane wydania OpenClaw zawierają go już domyślnie.
|
||||
- Starsze/niestandardowe instalacje mogą dodać go ręcznie za pomocą powyższych poleceń.
|
||||
2. Utwórz **Azure Bot** (App ID + secret + tenant ID).
|
||||
3. Zbuduj **pakiet aplikacji Teams**, który odwołuje się do bota i zawiera poniższe uprawnienia RSC.
|
||||
4. Prześlij/zainstaluj aplikację Teams w zespole (lub w zakresie osobistym dla DM-ów).
|
||||
4. Prześlij/zainstaluj aplikację Teams w zespole (lub w zakresie osobistym dla DM).
|
||||
5. Skonfiguruj `msteams` w `~/.openclaw/openclaw.json` (lub przez zmienne środowiskowe) i uruchom gateway.
|
||||
6. Gateway domyślnie nasłuchuje ruchu webhook Bot Framework pod adresem `/api/messages`.
|
||||
6. Gateway domyślnie nasłuchuje ruchu webhook Bot Framework na `/api/messages`.
|
||||
|
||||
## Konfiguracja Azure Bot (wymagania wstępne)
|
||||
|
||||
@ -162,16 +165,16 @@ Przed skonfigurowaniem OpenClaw musisz utworzyć zasób Azure Bot.
|
||||
1. Przejdź do [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
|
||||
2. Wypełnij kartę **Basics**:
|
||||
|
||||
| Pole | Wartość |
|
||||
| ------------------ | ------------------------------------------------------- |
|
||||
| Pole | Wartość |
|
||||
| ------------------ | -------------------------------------------------------- |
|
||||
| **Bot handle** | Nazwa Twojego bota, np. `openclaw-msteams` (musi być unikalna) |
|
||||
| **Subscription** | Wybierz swoją subskrypcję Azure |
|
||||
| **Resource group** | Utwórz nową lub użyj istniejącej |
|
||||
| **Subscription** | Wybierz swoją subskrypcję Azure |
|
||||
| **Resource group** | Utwórz nową lub użyj istniejącej |
|
||||
| **Pricing tier** | **Free** do developmentu/testów |
|
||||
| **Type of App** | **Single Tenant** (zalecane — patrz uwaga poniżej) |
|
||||
| **Creation type** | **Create new Microsoft App ID** |
|
||||
| **Type of App** | **Single Tenant** (zalecane - zobacz uwagę poniżej) |
|
||||
| **Creation type** | **Create new Microsoft App ID** |
|
||||
|
||||
> **Powiadomienie o wycofaniu:** Tworzenie nowych botów wielodostępnych zostało wycofane po 2025-07-31. Dla nowych botów używaj **Single Tenant**.
|
||||
> **Informacja o wycofaniu:** Tworzenie nowych botów wielodzierżawowych zostało wycofane po 2025-07-31. Dla nowych botów używaj **Single Tenant**.
|
||||
|
||||
3. Kliknij **Review + create** → **Create** (poczekaj ~1-2 minuty)
|
||||
|
||||
@ -179,16 +182,16 @@ Przed skonfigurowaniem OpenClaw musisz utworzyć zasób Azure Bot.
|
||||
|
||||
1. Przejdź do zasobu Azure Bot → **Configuration**
|
||||
2. Skopiuj **Microsoft App ID** → to jest Twoje `appId`
|
||||
3. Kliknij **Manage Password** → przejdź do App Registration
|
||||
3. Kliknij **Manage Password** → przejdź do rejestracji aplikacji
|
||||
4. W sekcji **Certificates & secrets** → **New client secret** → skopiuj **Value** → to jest Twoje `appPassword`
|
||||
5. Przejdź do **Overview** → skopiuj **Directory (tenant) ID** → to jest Twoje `tenantId`
|
||||
|
||||
### Krok 3: Skonfiguruj Messaging Endpoint
|
||||
### Krok 3: Skonfiguruj endpoint wiadomości
|
||||
|
||||
1. W Azure Bot → **Configuration**
|
||||
2. Ustaw **Messaging endpoint** na URL webhooka:
|
||||
- Produkcja: `https://your-domain.com/api/messages`
|
||||
- Local dev: użyj tunelu (zobacz [Local Development](#local-development-tunneling) poniżej)
|
||||
- Lokalny development: użyj tunelu (zobacz poniżej [Local Development](#local-development-tunneling))
|
||||
|
||||
### Krok 4: Włącz kanał Teams
|
||||
|
||||
@ -196,9 +199,151 @@ Przed skonfigurowaniem OpenClaw musisz utworzyć zasób Azure Bot.
|
||||
2. Kliknij **Microsoft Teams** → Configure → Save
|
||||
3. Zaakceptuj Terms of Service
|
||||
|
||||
## Uwierzytelnianie federacyjne (certyfikat + managed identity)
|
||||
|
||||
> Dodano w 2026.3.24
|
||||
|
||||
W środowiskach produkcyjnych OpenClaw obsługuje **uwierzytelnianie federacyjne** jako bezpieczniejszą alternatywę dla client secret. Dostępne są dwie metody:
|
||||
|
||||
### Opcja A: Uwierzytelnianie oparte na certyfikacie
|
||||
|
||||
Użyj certyfikatu PEM zarejestrowanego w rejestracji aplikacji Entra ID.
|
||||
|
||||
**Konfiguracja:**
|
||||
|
||||
1. Wygeneruj lub uzyskaj certyfikat (format PEM z kluczem prywatnym).
|
||||
2. W Entra ID → App Registration → **Certificates & secrets** → **Certificates** → prześlij certyfikat publiczny.
|
||||
|
||||
**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" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Zmienne środowiskowe:**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem`
|
||||
|
||||
### Opcja B: Azure Managed Identity
|
||||
|
||||
Użyj Azure Managed Identity do uwierzytelniania bez hasła. To idealne rozwiązanie dla wdrożeń na infrastrukturze Azure (AKS, App Service, maszyny wirtualne Azure), gdzie dostępna jest managed identity.
|
||||
|
||||
**Jak to działa:**
|
||||
|
||||
1. Pod/VM bota ma managed identity (przypisaną przez system lub użytkownika).
|
||||
2. **Federated identity credential** łączy managed identity z rejestracją aplikacji Entra ID.
|
||||
3. W czasie działania OpenClaw używa `@azure/identity` do pobierania tokenów z endpointu Azure IMDS (`169.254.169.254`).
|
||||
4. Token jest przekazywany do SDK Teams na potrzeby uwierzytelniania bota.
|
||||
|
||||
**Wymagania wstępne:**
|
||||
|
||||
- Infrastruktura Azure z włączoną managed identity (AKS workload identity, App Service, VM)
|
||||
- Utworzona federated identity credential w rejestracji aplikacji Entra ID
|
||||
- Dostęp sieciowy do IMDS (`169.254.169.254:80`) z poda/VM
|
||||
|
||||
**Config (managed identity przypisana przez system):**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
useManagedIdentity: true,
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Config (managed identity przypisana przez użytkownika):**
|
||||
|
||||
```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" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Zmienne środowiskowe:**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY=true`
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>` (tylko dla tożsamości przypisanej przez użytkownika)
|
||||
|
||||
### Konfiguracja AKS Workload Identity
|
||||
|
||||
Dla wdrożeń AKS używających workload identity:
|
||||
|
||||
1. **Włącz workload identity** w klastrze AKS.
|
||||
2. **Utwórz federated identity credential** w rejestracji aplikacji 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. **Dodaj adnotację do konta usługi Kubernetes** z identyfikatorem klienta aplikacji:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: my-bot-sa
|
||||
annotations:
|
||||
azure.workload.identity/client-id: "<APP_CLIENT_ID>"
|
||||
```
|
||||
|
||||
4. **Dodaj etykietę do poda** dla wstrzykiwania workload identity:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
labels:
|
||||
azure.workload.identity/use: "true"
|
||||
```
|
||||
|
||||
5. **Zapewnij dostęp sieciowy** do IMDS (`169.254.169.254`) — jeśli używasz NetworkPolicy, dodaj regułę egress zezwalającą na ruch do `169.254.169.254/32` na porcie 80.
|
||||
|
||||
### Porównanie typów uwierzytelniania
|
||||
|
||||
| Metoda | Konfiguracja | Zalety | Wady |
|
||||
| -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- |
|
||||
| **Client secret** | `appPassword` | Prosta konfiguracja | Wymaga rotacji sekretu, mniejsze bezpieczeństwo |
|
||||
| **Certificate** | `authType: "federated"` + `certificatePath` | Brak współdzielonego sekretu w sieci | Narzut związany z zarządzaniem certyfikatami |
|
||||
| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | Bez haseł, brak sekretów do zarządzania | Wymagana infrastruktura Azure |
|
||||
|
||||
**Zachowanie domyślne:** Gdy `authType` nie jest ustawione, OpenClaw domyślnie używa uwierzytelniania client secret. Istniejące konfiguracje nadal działają bez zmian.
|
||||
|
||||
## Local Development (tunelowanie)
|
||||
|
||||
Teams nie może połączyć się z `localhost`. Użyj tunelu do local developmentu:
|
||||
Teams nie może połączyć się z `localhost`. Do lokalnego developmentu użyj tunelu:
|
||||
|
||||
**Opcja A: ngrok**
|
||||
|
||||
@ -212,20 +357,20 @@ ngrok http 3978
|
||||
|
||||
```bash
|
||||
tailscale funnel 3978
|
||||
# Użyj swojego URL Tailscale Funnel jako messaging endpoint
|
||||
# Użyj swojego URL Tailscale funnel jako messaging endpoint
|
||||
```
|
||||
|
||||
## Teams Developer Portal (alternatywa)
|
||||
|
||||
Zamiast ręcznie tworzyć ZIP manifestu, możesz użyć [Teams Developer Portal](https://dev.teams.microsoft.com/apps):
|
||||
Zamiast ręcznie tworzyć ZIP z manifestem, możesz użyć [Teams Developer Portal](https://dev.teams.microsoft.com/apps):
|
||||
|
||||
1. Kliknij **+ New app**
|
||||
2. Wypełnij podstawowe informacje (nazwa, opis, informacje o deweloperze)
|
||||
2. Uzupełnij podstawowe informacje (nazwa, opis, informacje o deweloperze)
|
||||
3. Przejdź do **App features** → **Bot**
|
||||
4. Wybierz **Enter a bot ID manually** i wklej App ID swojego Azure Bot
|
||||
5. Zaznacz zakresy: **Personal**, **Team**, **Group Chat**
|
||||
6. Kliknij **Distribute** → **Download app package**
|
||||
7. W Teams: **Apps** → **Manage your apps** → **Upload a custom app** → wybierz ZIP
|
||||
7. W Teams: **Apps** → **Manage your apps** → **Upload a custom app** → wybierz plik ZIP
|
||||
|
||||
To często jest łatwiejsze niż ręczna edycja manifestów JSON.
|
||||
|
||||
@ -246,10 +391,10 @@ To często jest łatwiejsze niż ręczna edycja manifestów JSON.
|
||||
## Konfiguracja (minimalna, tylko tekst)
|
||||
|
||||
1. **Upewnij się, że plugin Microsoft Teams jest dostępny**
|
||||
- Bieżące spakowane wydania OpenClaw już go zawierają.
|
||||
- Bieżące paczkowane wydania OpenClaw zawierają go już domyślnie.
|
||||
- Starsze/niestandardowe instalacje mogą dodać go ręcznie:
|
||||
- Z npm: `openclaw plugins install @openclaw/msteams`
|
||||
- Z lokalnego checkouta: `openclaw plugins install ./path/to/local/msteams-plugin`
|
||||
- Z lokalnego checkoutu: `openclaw plugins install ./path/to/local/msteams-plugin`
|
||||
|
||||
2. **Rejestracja bota**
|
||||
- Utwórz Azure Bot (zobacz wyżej) i zanotuj:
|
||||
@ -285,37 +430,42 @@ To często jest łatwiejsze niż ręczna edycja manifestów JSON.
|
||||
- `MSTEAMS_APP_ID`
|
||||
- `MSTEAMS_APP_PASSWORD`
|
||||
- `MSTEAMS_TENANT_ID`
|
||||
- `MSTEAMS_AUTH_TYPE` (opcjonalnie: `"secret"` lub `"federated"`)
|
||||
- `MSTEAMS_CERTIFICATE_PATH` (federated + certyfikat)
|
||||
- `MSTEAMS_CERTIFICATE_THUMBPRINT` (opcjonalne, niewymagane do uwierzytelniania)
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY` (federated + managed identity)
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (tylko dla managed identity przypisanej przez użytkownika)
|
||||
|
||||
5. **Endpoint bota**
|
||||
- Ustaw Azure Bot Messaging Endpoint na:
|
||||
- `https://<host>:3978/api/messages` (lub wybraną przez Ciebie ścieżkę/port).
|
||||
- `https://<host>:3978/api/messages` (lub wybraną ścieżkę/port).
|
||||
|
||||
6. **Uruchom gateway**
|
||||
- Kanał Teams uruchamia się automatycznie, gdy bundled plugin lub ręcznie zainstalowany plugin jest dostępny i istnieje konfiguracja `msteams` z poświadczeniami.
|
||||
- Kanał Teams uruchamia się automatycznie, gdy bundled plugin lub ręcznie zainstalowany plugin jest dostępny, a konfiguracja `msteams` zawiera poświadczenia.
|
||||
|
||||
## Akcja informacji o członku
|
||||
|
||||
OpenClaw udostępnia opartą na Graph akcję `member-info` dla Microsoft Teams, aby agenci i automatyzacje mogli bezpośrednio z Microsoft Graph rozwiązywać szczegóły członków kanału (nazwa wyświetlana, e-mail, rola).
|
||||
OpenClaw udostępnia opartą na Graph akcję `member-info` dla Microsoft Teams, dzięki czemu agenci i automatyzacje mogą bezpośrednio z Microsoft Graph rozwiązywać szczegóły członków kanału (nazwa wyświetlana, e-mail, rola).
|
||||
|
||||
Wymagania:
|
||||
|
||||
- Uprawnienie RSC `Member.Read.Group` (już zawarte w zalecanym manifeście)
|
||||
- Dla wyszukiwań między zespołami: uprawnienie aplikacyjne Graph `User.Read.All` z consentem administratora
|
||||
- Uprawnienie RSC `Member.Read.Group` (już obecne w zalecanym manifeście)
|
||||
- Dla wyszukiwań między zespołami: uprawnienie aplikacyjne Graph `User.Read.All` z zgodą administratora
|
||||
|
||||
Akcja jest kontrolowana przez `channels.msteams.actions.memberInfo` (domyślnie: włączona, gdy dostępne są poświadczenia Graph).
|
||||
|
||||
## Kontekst historii
|
||||
|
||||
- `channels.msteams.historyLimit` kontroluje liczbę ostatnich wiadomości kanału/grupy opakowywanych do promptu.
|
||||
- Zapasowo używa `messages.groupChat.historyLimit`. Ustaw `0`, aby wyłączyć (domyślnie 50).
|
||||
- Pobrana historia wątku jest filtrowana przez allowlisty nadawców (`allowFrom` / `groupAllowFrom`), więc zasiewanie kontekstu wątku obejmuje tylko wiadomości od dozwolonych nadawców.
|
||||
- Cytowany kontekst załączników (`ReplyTo*` pochodzący z HTML odpowiedzi Teams) jest obecnie przekazywany tak, jak został odebrany.
|
||||
- Innymi słowy, allowlisty kontrolują, kto może wywołać agenta; obecnie filtrowane są tylko konkretne dodatkowe ścieżki kontekstu.
|
||||
- `channels.msteams.historyLimit` określa, ile ostatnich wiadomości z kanału/grupy jest opakowywanych do promptu.
|
||||
- Z fallbackiem do `messages.groupChat.historyLimit`. Ustaw `0`, aby wyłączyć (domyślnie 50).
|
||||
- Pobierana historia wątku jest filtrowana przez listy dozwolonych nadawców (`allowFrom` / `groupAllowFrom`), więc seedowanie kontekstu wątku obejmuje tylko wiadomości od dozwolonych nadawców.
|
||||
- Cytowany kontekst załączników (`ReplyTo*` pochodzący z HTML odpowiedzi Teams) jest obecnie przekazywany w otrzymanej postaci.
|
||||
- Innymi słowy, listy dozwolonych nadawców kontrolują, kto może wyzwolić agenta; obecnie filtrowane są tylko określone uzupełniające ścieżki kontekstu.
|
||||
- Historię DM można ograniczyć przez `channels.msteams.dmHistoryLimit` (tury użytkownika). Nadpisania per użytkownik: `channels.msteams.dms["<user_id>"].historyLimit`.
|
||||
|
||||
## Bieżące uprawnienia Teams RSC (manifest)
|
||||
|
||||
To są **istniejące resourceSpecific permissions** w naszym manifeście aplikacji Teams. Obowiązują tylko w zespole/czacie, gdzie aplikacja jest zainstalowana.
|
||||
To są **istniejące uprawnienia resourceSpecific** w manifeście naszej aplikacji Teams. Obowiązują tylko wewnątrz zespołu/czatu, w którym aplikacja jest zainstalowana.
|
||||
|
||||
**Dla kanałów (zakres zespołu):**
|
||||
|
||||
@ -331,7 +481,7 @@ To są **istniejące resourceSpecific permissions** w naszym manifeście aplikac
|
||||
|
||||
- `ChatMessage.Read.Chat` (Application) - odbieranie wszystkich wiadomości czatu grupowego bez @mention
|
||||
|
||||
## Przykładowy manifest Teams (zredagowany)
|
||||
## Przykładowy manifest Teams (z redakcją)
|
||||
|
||||
Minimalny, poprawny przykład z wymaganymi polami. Zastąp identyfikatory i URL-e.
|
||||
|
||||
@ -381,128 +531,133 @@ Minimalny, poprawny przykład z wymaganymi polami. Zastąp identyfikatory i URL-
|
||||
}
|
||||
```
|
||||
|
||||
### Zastrzeżenia dotyczące manifestu (pola obowiązkowe)
|
||||
### Zastrzeżenia dotyczące manifestu (pola wymagane)
|
||||
|
||||
- `bots[].botId` **musi** odpowiadać Azure Bot App ID.
|
||||
- `webApplicationInfo.id` **musi** odpowiadać Azure Bot App ID.
|
||||
- `bots[].scopes` musi zawierać powierzchnie, których chcesz używać (`personal`, `team`, `groupChat`).
|
||||
- `bots[].scopes` musi zawierać powierzchnie, których planujesz używać (`personal`, `team`, `groupChat`).
|
||||
- `bots[].supportsFiles: true` jest wymagane do obsługi plików w zakresie osobistym.
|
||||
- `authorization.permissions.resourceSpecific` musi zawierać uprawnienia odczytu/wysyłania kanałowego, jeśli chcesz obsługiwać ruch kanałowy.
|
||||
|
||||
### Aktualizacja istniejącej aplikacji
|
||||
|
||||
Aby zaktualizować już zainstalowaną aplikację Teams (np. w celu dodania uprawnień RSC):
|
||||
Aby zaktualizować już zainstalowaną aplikację Teams (np. dodać uprawnienia RSC):
|
||||
|
||||
1. Zaktualizuj `manifest.json`, dodając nowe ustawienia
|
||||
2. **Zwiększ pole `version`** (np. `1.0.0` → `1.1.0`)
|
||||
3. **Spakuj ponownie** manifest z ikonami (`manifest.json`, `outline.png`, `color.png`)
|
||||
4. Prześlij nowy zip:
|
||||
3. **Ponownie spakuj ZIP** z manifestem i ikonami (`manifest.json`, `outline.png`, `color.png`)
|
||||
4. Prześlij nowy plik zip:
|
||||
- **Opcja A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → znajdź swoją aplikację → Upload new version
|
||||
- **Opcja B (Sideload):** w Teams → Apps → Manage your apps → Upload a custom app
|
||||
5. **Dla kanałów zespołowych:** zainstaluj ponownie aplikację w każdym zespole, aby nowe uprawnienia zaczęły działać
|
||||
6. **Całkowicie zamknij i uruchom ponownie Teams** (nie tylko zamknij okno), aby wyczyścić cache metadanych aplikacji
|
||||
- **Opcja B (Sideload):** W Teams → Apps → Manage your apps → Upload a custom app
|
||||
5. **Dla kanałów zespołu:** ponownie zainstaluj aplikację w każdym zespole, aby nowe uprawnienia zaczęły obowiązywać
|
||||
6. **Całkowicie zamknij i uruchom ponownie Teams** (nie tylko zamknij okno), aby wyczyścić metadane aplikacji z cache
|
||||
|
||||
## Możliwości: tylko RSC vs Graph
|
||||
|
||||
### Z **samym Teams RSC** (aplikacja zainstalowana, bez uprawnień Graph API)
|
||||
### Z **samym Teams RSC** (aplikacja zainstalowana, bez uprawnień API Graph)
|
||||
|
||||
Działa:
|
||||
|
||||
- Odczyt treści **tekstowej** wiadomości kanałowych.
|
||||
- Wysyłanie **tekstowej** treści wiadomości kanałowych.
|
||||
- Odbieranie załączników plikowych w **osobistych (DM)**.
|
||||
- Odczyt **tekstu** wiadomości kanałowych.
|
||||
- Wysyłanie **tekstu** wiadomości kanałowych.
|
||||
- Odbieranie załączników plikowych w **zakresie osobistym (DM)**.
|
||||
|
||||
NIE działa:
|
||||
Nie działa:
|
||||
|
||||
- Zawartość **obrazów lub plików** w kanałach/grupach (payload zawiera tylko HTML stub).
|
||||
- Zawartość **obrazów lub plików** w kanałach/grupach (payload zawiera tylko stub HTML).
|
||||
- Pobieranie załączników przechowywanych w SharePoint/OneDrive.
|
||||
- Odczyt historii wiadomości (poza zdarzeniem webhooka na żywo).
|
||||
- Odczyt historii wiadomości (poza wydarzeniem webhooka na żywo).
|
||||
|
||||
### Z **Teams RSC + uprawnieniami aplikacyjnymi Microsoft Graph**
|
||||
|
||||
Dodaje:
|
||||
|
||||
- Pobieranie hostowanych treści (obrazów wklejonych do wiadomości).
|
||||
- Pobieranie hostowanych treści (obrazy wklejane do wiadomości).
|
||||
- Pobieranie załączników plikowych przechowywanych w SharePoint/OneDrive.
|
||||
- Odczyt historii wiadomości kanałów/czatów przez Graph.
|
||||
- Odczyt historii wiadomości kanału/czatu przez Graph.
|
||||
|
||||
### RSC vs Graph API
|
||||
|
||||
| Możliwość | Uprawnienia RSC | Graph API |
|
||||
| ----------------------- | -------------------- | ----------------------------------- |
|
||||
| **Wiadomości w czasie rzeczywistym** | Tak (przez webhook) | Nie (tylko polling) |
|
||||
| **Wiadomości historyczne** | Nie | Tak (można odpytywać historię) |
|
||||
| **Złożoność konfiguracji** | Tylko manifest aplikacji | Wymaga consentu administratora + przepływu tokena |
|
||||
| **Działa offline** | Nie (musi działać) | Tak (zapytanie w dowolnym momencie) |
|
||||
| Możliwość | Uprawnienia RSC | Graph API |
|
||||
| --------------------- | -------------------- | ----------------------------------- |
|
||||
| **Wiadomości w czasie rzeczywistym** | Tak (przez webhook) | Nie (tylko polling) |
|
||||
| **Wiadomości historyczne** | Nie | Tak (można odpytywać historię) |
|
||||
| **Złożoność konfiguracji** | Tylko manifest aplikacji | Wymaga zgody administratora + przepływu tokenów |
|
||||
| **Działa offline** | Nie (musi działać) | Tak (zapytanie możliwe w dowolnym momencie) |
|
||||
|
||||
**Podsumowanie:** RSC służy do nasłuchiwania w czasie rzeczywistym; Graph API służy do dostępu historycznego. Aby nadrobić wiadomości pominięte podczas offline, potrzebujesz Graph API z `ChannelMessage.Read.All` (wymaga consentu administratora).
|
||||
**Podsumowanie:** RSC służy do nasłuchu w czasie rzeczywistym; Graph API służy do dostępu historycznego. Aby nadrobić pominięte wiadomości podczas pracy offline, potrzebujesz Graph API z `ChannelMessage.Read.All` (wymaga zgody administratora).
|
||||
|
||||
## Media + historia z włączonym Graph (wymagane dla kanałów)
|
||||
## Media + historia z Graph (wymagane dla kanałów)
|
||||
|
||||
Jeśli potrzebujesz obrazów/plików w **kanałach** lub chcesz pobierać **historię wiadomości**, musisz włączyć uprawnienia Microsoft Graph i przyznać consent administratora.
|
||||
Jeśli potrzebujesz obrazów/plików w **kanałach** lub chcesz pobierać **historię wiadomości**, musisz włączyć uprawnienia Microsoft Graph i udzielić zgody administratora.
|
||||
|
||||
1. W Entra ID (Azure AD) **App Registration** dodaj uprawnienia aplikacyjne Microsoft Graph:
|
||||
- `ChannelMessage.Read.All` (załączniki kanałowe + historia)
|
||||
- `Chat.Read.All` lub `ChatMessage.Read.All` (czaty grupowe)
|
||||
2. **Przyznaj consent administratora** dla tenant.
|
||||
2. **Udziel zgody administratora** dla tenantu.
|
||||
3. Zwiększ **wersję manifestu** aplikacji Teams, prześlij go ponownie i **zainstaluj aplikację ponownie w Teams**.
|
||||
4. **Całkowicie zamknij i uruchom ponownie Teams**, aby wyczyścić cache metadanych aplikacji.
|
||||
4. **Całkowicie zamknij i uruchom ponownie Teams**, aby wyczyścić metadane aplikacji z cache.
|
||||
|
||||
**Dodatkowe uprawnienie dla wzmiankowania użytkowników:** Wzmianki @ użytkowników działają od razu dla użytkowników obecnych w konwersacji. Jeśli jednak chcesz dynamicznie wyszukiwać i wzmiankować użytkowników, którzy **nie są w bieżącej konwersacji**, dodaj uprawnienie aplikacyjne `User.Read.All` i przyznaj consent administratora.
|
||||
**Dodatkowe uprawnienie dla wzmianek o użytkownikach:** Wzmianki @ użytkowników działają od razu dla użytkowników będących uczestnikami rozmowy. Jeśli jednak chcesz dynamicznie wyszukiwać i oznaczać użytkowników, którzy **nie są w bieżącej rozmowie**, dodaj uprawnienie aplikacyjne `User.Read.All` i udziel zgody administratora.
|
||||
|
||||
## Znane ograniczenia
|
||||
|
||||
### Timeouty webhooków
|
||||
### Limity czasu webhooka
|
||||
|
||||
Teams dostarcza wiadomości przez webhook HTTP. Jeśli przetwarzanie trwa zbyt długo (np. wolne odpowiedzi LLM), możesz zobaczyć:
|
||||
Teams dostarcza wiadomości przez webhook HTTP. Jeśli przetwarzanie trwa zbyt długo (np. powolne odpowiedzi LLM), możesz zobaczyć:
|
||||
|
||||
- Timeouty gateway
|
||||
- Ponawianie wiadomości przez Teams (powodujące duplikaty)
|
||||
- Utracone odpowiedzi
|
||||
- przekroczenia czasu gateway
|
||||
- ponawianie wiadomości przez Teams (powodujące duplikaty)
|
||||
- porzucone odpowiedzi
|
||||
|
||||
OpenClaw obsługuje to, szybko zwracając odpowiedź i wysyłając odpowiedzi proaktywnie, ale bardzo wolne odpowiedzi mogą nadal powodować problemy.
|
||||
OpenClaw obsługuje to przez szybki zwrot odpowiedzi i proaktywne wysyłanie odpowiedzi, ale bardzo wolne odpowiedzi nadal mogą powodować problemy.
|
||||
|
||||
### Formatowanie
|
||||
|
||||
Markdown Teams jest bardziej ograniczony niż w Slack lub Discord:
|
||||
|
||||
- Podstawowe formatowanie działa: **pogrubienie**, _kursywa_, `code`, linki
|
||||
- Złożony Markdown (tabele, zagnieżdżone listy) może nie renderować się poprawnie
|
||||
- Działa podstawowe formatowanie: **bold**, _italic_, `code`, linki
|
||||
- Złożony markdown (tabele, zagnieżdżone listy) może renderować się niepoprawnie
|
||||
- Adaptive Cards są obsługiwane dla ankiet i dowolnych wysyłek kart (zobacz poniżej)
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
Kluczowe ustawienia (zobacz `/gateway/configuration`, aby poznać współdzielone wzorce kanałów):
|
||||
Kluczowe ustawienia (wspólne wzorce kanałów znajdziesz w `/gateway/configuration`):
|
||||
|
||||
- `channels.msteams.enabled`: włącz/wyłącz kanał.
|
||||
- `channels.msteams.enabled`: włącza/wyłącza kanał.
|
||||
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: poświadczenia bota.
|
||||
- `channels.msteams.webhook.port` (domyślnie `3978`)
|
||||
- `channels.msteams.webhook.path` (domyślnie `/api/messages`)
|
||||
- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (domyślnie: pairing)
|
||||
- `channels.msteams.allowFrom`: allowlista DM (zalecane identyfikatory obiektów AAD). Kreator rozwiązuje nazwy na identyfikatory podczas konfiguracji, gdy dostępny jest Graph.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching`: przełącznik awaryjny do ponownego włączenia dopasowywania zmiennych UPN-ów/nazw wyświetlanych oraz bezpośredniego routowania po nazwie zespołu/kanału.
|
||||
- `channels.msteams.textChunkLimit`: rozmiar chunków tekstu wychodzącego.
|
||||
- `channels.msteams.chunkMode`: `length` (domyślnie) lub `newline`, aby dzielić po pustych liniach (granice akapitów) przed chunkowaniem po długości.
|
||||
- `channels.msteams.mediaAllowHosts`: allowlista hostów dla przychodzących załączników (domyślnie domeny Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts`: allowlista hostów, dla których dołączane są nagłówki Authorization przy ponownych próbach pobierania mediów (domyślnie hosty Graph + Bot Framework).
|
||||
- `channels.msteams.requireMention`: wymagaj @mention w kanałach/grupach (domyślnie true).
|
||||
- `channels.msteams.allowFrom`: lista dozwolonych dla DM (zalecane identyfikatory obiektów AAD). Kreator rozwiązuje nazwy do identyfikatorów podczas konfiguracji, gdy dostęp do Graph jest dostępny.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching`: przełącznik awaryjny przywracający dopasowywanie po zmiennych UPN/nazwach wyświetlanych oraz bezpośredni routing po nazwach zespołów/kanałów.
|
||||
- `channels.msteams.textChunkLimit`: rozmiar fragmentów tekstu wychodzącego.
|
||||
- `channels.msteams.chunkMode`: `length` (domyślnie) lub `newline`, aby dzielić po pustych wierszach (granice akapitów) przed dzieleniem według długości.
|
||||
- `channels.msteams.mediaAllowHosts`: lista dozwolonych hostów dla przychodzących załączników (domyślnie domeny Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts`: lista dozwolonych hostów do dołączania nagłówków Authorization przy ponownych próbach pobrania mediów (domyślnie hosty Graph + Bot Framework).
|
||||
- `channels.msteams.requireMention`: wymaga @mention w kanałach/grupach (domyślnie true).
|
||||
- `channels.msteams.replyStyle`: `thread | top-level` (zobacz [Styl odpowiedzi](#reply-style-threads-vs-posts)).
|
||||
- `channels.msteams.teams.<teamId>.replyStyle`: nadpisanie per zespół.
|
||||
- `channels.msteams.teams.<teamId>.requireMention`: nadpisanie per zespół.
|
||||
- `channels.msteams.teams.<teamId>.tools`: domyślne nadpisania polityki narzędzi per zespół (`allow`/`deny`/`alsoAllow`) używane, gdy brak nadpisania kanałowego.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender`: domyślne nadpisania polityki narzędzi per nadawca dla zespołu (obsługiwany wildcard `"*"`).
|
||||
- `channels.msteams.teams.<teamId>.tools`: domyślne nadpisania polityki narzędzi per zespół (`allow`/`deny`/`alsoAllow`) używane, gdy brakuje nadpisania kanału.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender`: domyślne nadpisania polityki narzędzi per zespół i nadawcę (obsługiwany wildcard `"*"`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: nadpisanie per kanał.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: nadpisanie per kanał.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: nadpisania polityki narzędzi per kanał (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: nadpisania polityki narzędzi per nadawca dla kanału (obsługiwany wildcard `"*"`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: nadpisania polityki narzędzi per kanał i nadawcę (obsługiwany wildcard `"*"`).
|
||||
- Klucze `toolsBySender` powinny używać jawnych prefiksów:
|
||||
`id:`, `e164:`, `username:`, `name:` (starsze klucze bez prefiksu nadal mapują tylko do `id:`).
|
||||
- `channels.msteams.actions.memberInfo`: włącz lub wyłącz opartą na Graph akcję informacji o członku (domyślnie: włączona, gdy dostępne są poświadczenia Graph).
|
||||
- `channels.msteams.sharePointSiteId`: identyfikator witryny SharePoint do przesyłania plików w czatach grupowych/kanałach (zobacz [Wysyłanie plików w czatach grupowych](#sending-files-in-group-chats)).
|
||||
`id:`, `e164:`, `username:`, `name:` (starsze klucze bez prefiksu nadal mapują się tylko do `id:`).
|
||||
- `channels.msteams.actions.memberInfo`: włącza lub wyłącza opartą na Graph akcję informacji o członku (domyślnie: włączona, gdy dostępne są poświadczenia Graph).
|
||||
- `channels.msteams.authType`: typ uwierzytelniania — `"secret"` (domyślnie) lub `"federated"`.
|
||||
- `channels.msteams.certificatePath`: ścieżka do pliku certyfikatu PEM (federated + uwierzytelnianie certyfikatem).
|
||||
- `channels.msteams.certificateThumbprint`: odcisk palca certyfikatu (opcjonalny, niewymagany do uwierzytelniania).
|
||||
- `channels.msteams.useManagedIdentity`: włącza uwierzytelnianie managed identity (tryb federated).
|
||||
- `channels.msteams.managedIdentityClientId`: identyfikator klienta dla managed identity przypisanej przez użytkownika.
|
||||
- `channels.msteams.sharePointSiteId`: identyfikator witryny SharePoint dla wysyłania plików w czatach grupowych/kanałach (zobacz [Wysyłanie plików w czatach grupowych](#sending-files-in-group-chats)).
|
||||
|
||||
## Routowanie i sesje
|
||||
## Routing i sesje
|
||||
|
||||
- Klucze sesji mają standardowy format agenta (zobacz [/concepts/session](/concepts/session)):
|
||||
- Klucze sesji są zgodne ze standardowym formatem agenta (zobacz [/concepts/session](/pl/concepts/session)):
|
||||
- Wiadomości bezpośrednie współdzielą główną sesję (`agent:<agentId>:<mainKey>`).
|
||||
- Wiadomości kanałowe/grupowe używają identyfikatora konwersacji:
|
||||
- `agent:<agentId>:msteams:channel:<conversationId>`
|
||||
@ -510,19 +665,19 @@ Kluczowe ustawienia (zobacz `/gateway/configuration`, aby poznać współdzielon
|
||||
|
||||
## Styl odpowiedzi: wątki vs posty
|
||||
|
||||
Teams niedawno wprowadził dwa style UI kanałów na tym samym bazowym modelu danych:
|
||||
Teams niedawno wprowadził dwa style interfejsu kanałów nad tym samym bazowym modelem danych:
|
||||
|
||||
| Styl | Opis | Zalecane `replyStyle` |
|
||||
| ------------------------ | --------------------------------------------------------- | --------------------- |
|
||||
| **Posts** (klasyczny) | Wiadomości pojawiają się jako karty z odpowiedziami w wątku pod spodem | `thread` (domyślnie) |
|
||||
| **Threads** (jak Slack) | Wiadomości płyną liniowo, bardziej jak w Slack | `top-level` |
|
||||
| Styl | Opis | Zalecane `replyStyle` |
|
||||
| ----------------------- | --------------------------------------------------------- | --------------------- |
|
||||
| **Posts** (klasyczny) | Wiadomości pojawiają się jako karty z odpowiedziami we wątku pod spodem | `thread` (domyślnie) |
|
||||
| **Threads** (jak Slack) | Wiadomości płyną liniowo, bardziej jak w Slack | `top-level` |
|
||||
|
||||
**Problem:** API Teams nie ujawnia, którego stylu UI używa kanał. Jeśli użyjesz niewłaściwego `replyStyle`:
|
||||
**Problem:** API Teams nie ujawnia, którego stylu interfejsu używa kanał. Jeśli użyjesz niewłaściwego `replyStyle`:
|
||||
|
||||
- `thread` w kanale w stylu Threads → odpowiedzi pojawiają się niezręcznie zagnieżdżone
|
||||
- `top-level` w kanale w stylu Posts → odpowiedzi pojawiają się jako osobne posty najwyższego poziomu zamiast we wątku
|
||||
|
||||
**Rozwiązanie:** Skonfiguruj `replyStyle` per kanał w zależności od tego, jak kanał jest skonfigurowany:
|
||||
**Rozwiązanie:** Skonfiguruj `replyStyle` per kanał na podstawie sposobu skonfigurowania kanału:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -545,15 +700,15 @@ Teams niedawno wprowadził dwa style UI kanałów na tym samym bazowym modelu da
|
||||
|
||||
## Załączniki i obrazy
|
||||
|
||||
**Bieżące ograniczenia:**
|
||||
**Obecne ograniczenia:**
|
||||
|
||||
- **DM-y:** obrazy i załączniki plikowe działają przez botowe API plików Teams.
|
||||
- **Kanały/grupy:** załączniki znajdują się w pamięci masowej M365 (SharePoint/OneDrive). Payload webhooka zawiera tylko HTML stub, a nie faktyczne bajty pliku. **Do pobierania załączników kanałowych wymagane są uprawnienia Graph API**.
|
||||
- **DM-y:** obrazy i załączniki plikowe działają przez interfejsy API plików bota Teams.
|
||||
- **Kanały/grupy:** załączniki są przechowywane w M365 (SharePoint/OneDrive). Payload webhooka zawiera tylko stub HTML, a nie rzeczywiste bajty pliku. **Do pobierania załączników kanałowych wymagane są uprawnienia Graph API**.
|
||||
- Dla jawnych wysyłek rozpoczynających się od pliku użyj `action=upload-file` z `media` / `filePath` / `path`; opcjonalne `message` staje się dołączonym tekstem/komentarzem, a `filename` nadpisuje nazwę przesyłanego pliku.
|
||||
|
||||
Bez uprawnień Graph wiadomości kanałowe z obrazami będą odbierane jako tylko tekstowe (zawartość obrazu nie jest dostępna dla bota).
|
||||
Bez uprawnień Graph wiadomości kanałowe z obrazami będą odbierane tylko jako tekst (zawartość obrazu nie jest dostępna dla bota).
|
||||
Domyślnie OpenClaw pobiera media tylko z nazw hostów Microsoft/Teams. Nadpisz to przez `channels.msteams.mediaAllowHosts` (użyj `["*"]`, aby zezwolić na dowolny host).
|
||||
Nagłówki Authorization są dołączane tylko dla hostów z `channels.msteams.mediaAuthAllowHosts` (domyślnie hosty Graph + Bot Framework). Utrzymuj tę listę restrykcyjną (unikaj wielodostępnych sufiksów).
|
||||
Nagłówki Authorization są dołączane tylko dla hostów z `channels.msteams.mediaAuthAllowHosts` (domyślnie hosty Graph + Bot Framework). Utrzymuj tę listę restrykcyjną (unikaj sufiksów wielodzierżawowych).
|
||||
|
||||
## Wysyłanie plików w czatach grupowych
|
||||
|
||||
@ -561,21 +716,21 @@ Boty mogą wysyłać pliki w DM-ach przy użyciu przepływu FileConsentCard (wbu
|
||||
|
||||
| Kontekst | Sposób wysyłania plików | Wymagana konfiguracja |
|
||||
| ------------------------ | ------------------------------------------ | ---------------------------------------------- |
|
||||
| **DM-y** | FileConsentCard → użytkownik akceptuje → bot przesyła | Działa od razu |
|
||||
| **Czaty grupowe/kanały** | Przesłanie do SharePoint → link współdzielenia | Wymaga `sharePointSiteId` + uprawnień Graph |
|
||||
| **DM-y** | FileConsentCard → użytkownik akceptuje → bot przesyła plik | Działa od razu |
|
||||
| **Czaty grupowe/kanały** | Przesłanie do SharePoint → udostępnienie linku | Wymaga `sharePointSiteId` + uprawnień Graph |
|
||||
| **Obrazy (dowolny kontekst)** | Inline zakodowane w Base64 | Działa od razu |
|
||||
|
||||
### Dlaczego czaty grupowe wymagają SharePoint
|
||||
|
||||
Boty nie mają osobistego dysku OneDrive (endpoint Graph API `/me/drive` nie działa dla tożsamości aplikacyjnych). Aby wysyłać pliki w czatach grupowych/kanałach, bot przesyła je do **witryny SharePoint** i tworzy link współdzielenia.
|
||||
Boty nie mają osobistego dysku OneDrive (endpoint Graph API `/me/drive` nie działa dla tożsamości aplikacyjnych). Aby wysyłać pliki w czatach grupowych/kanałach, bot przesyła je do **witryny SharePoint** i tworzy link do udostępnienia.
|
||||
|
||||
### Konfiguracja
|
||||
|
||||
1. **Dodaj uprawnienia Graph API** w Entra ID (Azure AD) → App Registration:
|
||||
- `Sites.ReadWrite.All` (Application) - przesyłanie plików do SharePoint
|
||||
- `Chat.Read.All` (Application) - opcjonalnie, umożliwia linki współdzielenia per użytkownik
|
||||
- `Chat.Read.All` (Application) - opcjonalne, włącza linki udostępniania per użytkownik
|
||||
|
||||
2. **Przyznaj consent administratora** dla tenant.
|
||||
2. **Udziel zgody administratora** dla tenantu.
|
||||
|
||||
3. **Pobierz identyfikator witryny SharePoint:**
|
||||
|
||||
@ -604,20 +759,20 @@ Boty nie mają osobistego dysku OneDrive (endpoint Graph API `/me/drive` nie dzi
|
||||
}
|
||||
```
|
||||
|
||||
### Zachowanie współdzielenia
|
||||
### Zachowanie udostępniania
|
||||
|
||||
| Uprawnienie | Zachowanie współdzielenia |
|
||||
| ---------------------------------------- | ---------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` tylko | Link współdzielenia w całej organizacji (każdy w org może uzyskać dostęp) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Link współdzielenia per użytkownik (dostęp mają tylko członkowie czatu) |
|
||||
| Uprawnienie | Zachowanie udostępniania |
|
||||
| --------------------------------------- | --------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` tylko | Link udostępniania dla całej organizacji (dostępny dla każdego w organizacji) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Link udostępniania per użytkownik (dostępny tylko dla członków czatu) |
|
||||
|
||||
Współdzielenie per użytkownik jest bezpieczniejsze, ponieważ tylko uczestnicy czatu mogą uzyskać dostęp do pliku. Jeśli brakuje uprawnienia `Chat.Read.All`, bot wraca do współdzielenia w całej organizacji.
|
||||
Udostępnianie per użytkownik jest bezpieczniejsze, ponieważ tylko uczestnicy czatu mają dostęp do pliku. Jeśli brakuje uprawnienia `Chat.Read.All`, bot wraca do udostępniania dla całej organizacji.
|
||||
|
||||
### Zachowanie zapasowe
|
||||
### Zachowanie fallback
|
||||
|
||||
| Scenariusz | Wynik |
|
||||
| ------------------------------------------------- | -------------------------------------------------- |
|
||||
| Czat grupowy + plik + skonfigurowane `sharePointSiteId` | Przesłanie do SharePoint, wysłanie linku współdzielenia |
|
||||
| Czat grupowy + plik + skonfigurowane `sharePointSiteId` | Przesłanie do SharePoint, wysłanie linku udostępniania |
|
||||
| Czat grupowy + plik + brak `sharePointSiteId` | Próba przesłania do OneDrive (może się nie udać), wysłanie tylko tekstu |
|
||||
| Czat osobisty + plik | Przepływ FileConsentCard (działa bez SharePoint) |
|
||||
| Dowolny kontekst + obraz | Inline zakodowane w Base64 (działa bez SharePoint) |
|
||||
@ -637,9 +792,9 @@ OpenClaw wysyła ankiety Teams jako Adaptive Cards (nie ma natywnego API ankiet
|
||||
|
||||
## Adaptive Cards (dowolne)
|
||||
|
||||
Wyślij dowolny JSON Adaptive Card do użytkowników lub konwersacji Teams za pomocą narzędzia `message` lub CLI.
|
||||
Wysyłaj dowolny JSON Adaptive Card do użytkowników lub konwersacji Teams przy użyciu narzędzia `message` lub CLI.
|
||||
|
||||
Parametr `card` akceptuje obiekt JSON Adaptive Card. Gdy podano `card`, tekst wiadomości jest opcjonalny.
|
||||
Parametr `card` akceptuje obiekt JSON Adaptive Card. Gdy `card` jest podane, tekst wiadomości jest opcjonalny.
|
||||
|
||||
**Narzędzie agenta:**
|
||||
|
||||
@ -664,26 +819,26 @@ openclaw message send --channel msteams \
|
||||
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
|
||||
```
|
||||
|
||||
Zobacz [dokumentację Adaptive Cards](https://adaptivecards.io/), aby poznać schemat kart i przykłady. Szczegóły formatu target znajdziesz poniżej w [Formatach target](#target-formats).
|
||||
Zobacz [dokumentację Adaptive Cards](https://adaptivecards.io/), aby poznać schemat karty i przykłady. Szczegóły formatu celu znajdziesz poniżej w [Formatach celu](#target-formats).
|
||||
|
||||
## Formaty target
|
||||
## Formaty celu
|
||||
|
||||
Targety MSTeams używają prefiksów do rozróżniania użytkowników i konwersacji:
|
||||
Cele MSTeams używają prefiksów do rozróżniania użytkowników i konwersacji:
|
||||
|
||||
| Typ targetu | Format | Przykład |
|
||||
| -------------------- | -------------------------------- | --------------------------------------------------- |
|
||||
| Użytkownik (po ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Użytkownik (po nazwie) | `user:<display-name>` | `user:John Smith` (wymaga Graph API) |
|
||||
| Grupa/kanał | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Grupa/kanał (raw) | `<conversation-id>` | `19:abc123...@thread.tacv2` (jeśli zawiera `@thread`) |
|
||||
| Typ celu | Format | Przykład |
|
||||
| --------------------- | -------------------------------- | --------------------------------------------------- |
|
||||
| Użytkownik (według ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Użytkownik (według nazwy) | `user:<display-name>` | `user:John Smith` (wymaga Graph API) |
|
||||
| Grupa/kanał | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Grupa/kanał (raw) | `<conversation-id>` | `19:abc123...@thread.tacv2` (jeśli zawiera `@thread`) |
|
||||
|
||||
**Przykłady CLI:**
|
||||
|
||||
```bash
|
||||
# Wyślij do użytkownika po ID
|
||||
# Wyślij do użytkownika według ID
|
||||
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"
|
||||
|
||||
# Wyślij do użytkownika po nazwie wyświetlanej (wywołuje wyszukiwanie przez Graph API)
|
||||
# Wyślij do użytkownika według nazwy wyświetlanej (wywołuje wyszukiwanie przez Graph API)
|
||||
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
|
||||
|
||||
# Wyślij do czatu grupowego lub kanału
|
||||
@ -718,14 +873,14 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread.
|
||||
}
|
||||
```
|
||||
|
||||
Uwaga: bez prefiksu `user:` nazwy domyślnie trafiają do rozwiązywania grup/zespołów. Zawsze używaj `user:`, gdy kierujesz wiadomość do osób po nazwie wyświetlanej.
|
||||
Uwaga: bez prefiksu `user:` nazwy domyślnie trafiają do rozwiązywania grup/zespołów. Zawsze używaj `user:`, gdy kierujesz wiadomości do osób po nazwie wyświetlanej.
|
||||
|
||||
## Wiadomości proaktywne
|
||||
|
||||
- Wiadomości proaktywne są możliwe **dopiero po** interakcji użytkownika, ponieważ dopiero wtedy zapisujemy referencje konwersacji.
|
||||
- Zobacz `/gateway/configuration`, aby poznać `dmPolicy` i bramkowanie allowlistą.
|
||||
- Zobacz `/gateway/configuration`, aby poznać `dmPolicy` i kontrolę przez listy dozwolonych.
|
||||
|
||||
## Identyfikatory zespołów i kanałów (częsta pułapka)
|
||||
## Identyfikatory zespołów i kanałów (częsty problem)
|
||||
|
||||
Parametr zapytania `groupId` w URL-ach Teams **NIE** jest identyfikatorem zespołu używanym do konfiguracji. Wyodrębnij identyfikatory ze ścieżki URL:
|
||||
|
||||
@ -734,7 +889,7 @@ Parametr zapytania `groupId` w URL-ach Teams **NIE** jest identyfikatorem zespo
|
||||
```
|
||||
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
|
||||
└────────────────────────────┘
|
||||
Identyfikator zespołu (zdekoduj URL)
|
||||
Team ID (zdekoduj URL)
|
||||
```
|
||||
|
||||
**URL kanału:**
|
||||
@ -742,70 +897,70 @@ https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?gro
|
||||
```
|
||||
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
|
||||
└─────────────────────────┘
|
||||
Identyfikator kanału (zdekoduj URL)
|
||||
Channel ID (zdekoduj URL)
|
||||
```
|
||||
|
||||
**Dla konfiguracji:**
|
||||
**Do konfiguracji:**
|
||||
|
||||
- Identyfikator zespołu = segment ścieżki po `/team/` (po zdekodowaniu URL, np. `19:Bk4j...@thread.tacv2`)
|
||||
- Identyfikator kanału = segment ścieżki po `/channel/` (po zdekodowaniu URL)
|
||||
- Team ID = segment ścieżki po `/team/` (po zdekodowaniu URL, np. `19:Bk4j...@thread.tacv2`)
|
||||
- Channel ID = segment ścieżki po `/channel/` (po zdekodowaniu URL)
|
||||
- **Ignoruj** parametr zapytania `groupId`
|
||||
|
||||
## Kanały prywatne
|
||||
|
||||
Boty mają ograniczone wsparcie w kanałach prywatnych:
|
||||
Boty mają ograniczoną obsługę w kanałach prywatnych:
|
||||
|
||||
| Funkcja | Kanały standardowe | Kanały prywatne |
|
||||
| ---------------------------- | ------------------ | ---------------------- |
|
||||
| Instalacja bota | Tak | Ograniczona |
|
||||
| Wiadomości w czasie rzeczywistym (webhook) | Tak | Może nie działać |
|
||||
| Wiadomości w czasie rzeczywistym (webhook) | Tak | Może nie działać |
|
||||
| Uprawnienia RSC | Tak | Mogą działać inaczej |
|
||||
| @mentions | Tak | Jeśli bot jest dostępny |
|
||||
| Historia przez Graph API | Tak | Tak (z uprawnieniami) |
|
||||
|
||||
**Obejścia, jeśli kanały prywatne nie działają:**
|
||||
|
||||
1. Używaj kanałów standardowych do interakcji z botem
|
||||
2. Używaj DM-ów — użytkownicy zawsze mogą napisać bezpośrednio do bota
|
||||
1. Używaj standardowych kanałów do interakcji z botem
|
||||
2. Używaj DM-ów — użytkownicy zawsze mogą napisać do bota bezpośrednio
|
||||
3. Używaj Graph API do dostępu historycznego (wymaga `ChannelMessage.Read.All`)
|
||||
|
||||
## Rozwiązywanie problemów
|
||||
|
||||
### Typowe problemy
|
||||
|
||||
- **Obrazy nie pokazują się w kanałach:** brakuje uprawnień Graph lub consentu administratora. Zainstaluj ponownie aplikację Teams i całkowicie zamknij/otwórz Teams.
|
||||
- **Brak odpowiedzi w kanale:** domyślnie wymagane są wzmianki; ustaw `channels.msteams.requireMention=false` lub skonfiguruj per zespół/kanał.
|
||||
- **Niezgodność wersji (Teams nadal pokazuje stary manifest):** usuń i dodaj aplikację ponownie oraz całkowicie zamknij Teams, aby odświeżyć.
|
||||
- **401 Unauthorized z webhooka:** oczekiwane przy ręcznych testach bez Azure JWT — oznacza, że endpoint jest osiągalny, ale autoryzacja się nie powiodła. Użyj Azure Web Chat do poprawnego testowania.
|
||||
- **Obrazy nie pokazują się w kanałach:** brakuje uprawnień Graph lub zgody administratora. Zainstaluj ponownie aplikację Teams i całkowicie zamknij/otwórz ponownie Teams.
|
||||
- **Brak odpowiedzi w kanale:** wzmianki są domyślnie wymagane; ustaw `channels.msteams.requireMention=false` lub skonfiguruj to per zespół/kanał.
|
||||
- **Niezgodność wersji (Teams nadal pokazuje stary manifest):** usuń i dodaj aplikację ponownie oraz całkowicie zamknij Teams, aby odświeżyć dane.
|
||||
- **401 Unauthorized z webhooka:** oczekiwane przy ręcznych testach bez JWT z Azure — oznacza, że endpoint jest osiągalny, ale uwierzytelnianie nie przeszło. Do poprawnego testu użyj Azure Web Chat.
|
||||
|
||||
### Błędy przesyłania manifestu
|
||||
|
||||
- **"Icon file cannot be empty":** manifest odwołuje się do plików ikon, które mają 0 bajtów. Utwórz poprawne ikony PNG (`outline.png` 32x32, `color.png` 192x192).
|
||||
- **"webApplicationInfo.Id already in use":** aplikacja nadal jest zainstalowana w innym zespole/czacie. Znajdź ją i odinstaluj najpierw albo odczekaj 5-10 minut na propagację.
|
||||
- **"Something went wrong" przy przesyłaniu:** prześlij przez [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), otwórz DevTools przeglądarki (F12) → zakładka Network i sprawdź body odpowiedzi, aby zobaczyć faktyczny błąd.
|
||||
- **Sideload nie działa:** spróbuj opcji „Upload an app to your org's app catalog” zamiast „Upload a custom app” — często omija to ograniczenia sideload.
|
||||
- **"Icon file cannot be empty":** manifest odwołuje się do plików ikon mających 0 bajtów. Utwórz poprawne ikony PNG (`outline.png` 32x32, `color.png` 192x192).
|
||||
- **"webApplicationInfo.Id already in use":** aplikacja jest nadal zainstalowana w innym zespole/czacie. Najpierw ją znajdź i odinstaluj albo poczekaj 5-10 minut na propagację.
|
||||
- **"Something went wrong" podczas przesyłania:** prześlij przez [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), otwórz DevTools przeglądarki (F12) → kartę Network i sprawdź body odpowiedzi, aby zobaczyć rzeczywisty błąd.
|
||||
- **Niepowodzenie sideload:** spróbuj użyć „Upload an app to your org's app catalog” zamiast „Upload a custom app” — często omija to ograniczenia sideload.
|
||||
|
||||
### Uprawnienia RSC nie działają
|
||||
|
||||
1. Zweryfikuj, że `webApplicationInfo.id` dokładnie odpowiada App ID Twojego bota
|
||||
1. Sprawdź, czy `webApplicationInfo.id` dokładnie odpowiada App ID Twojego bota
|
||||
2. Prześlij aplikację ponownie i zainstaluj ją ponownie w zespole/czacie
|
||||
3. Sprawdź, czy administrator Twojej organizacji nie zablokował uprawnień RSC
|
||||
3. Sprawdź, czy administrator organizacji nie zablokował uprawnień RSC
|
||||
4. Potwierdź, że używasz właściwego zakresu: `ChannelMessage.Read.Group` dla zespołów, `ChatMessage.Read.Chat` dla czatów grupowych
|
||||
|
||||
## Odwołania
|
||||
## Odnośniki
|
||||
|
||||
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - przewodnik konfiguracji Azure Bot
|
||||
- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - tworzenie/zarządzanie aplikacjami Teams
|
||||
- [Schemat manifestu aplikacji Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
|
||||
- [Odbieranie wiadomości kanałowych z RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
|
||||
- [Dokumentacja uprawnień RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
|
||||
- [Obsługa plików bota Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (kanał/grupa wymaga Graph)
|
||||
- [Wiadomości proaktywne](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
- [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
|
||||
- [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
|
||||
- [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
|
||||
- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (kanały/grupy wymagają Graph)
|
||||
- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Przegląd kanałów](/pl/channels) — wszystkie obsługiwane kanały
|
||||
- [Channels Overview](/pl/channels) — wszystkie obsługiwane kanały
|
||||
- [Pairing](/pl/channels/pairing) — uwierzytelnianie DM i przepływ parowania
|
||||
- [Grupy](/pl/channels/groups) — zachowanie czatów grupowych i bramkowanie wzmiankami
|
||||
- [Routowanie kanałów](/pl/channels/channel-routing) — routowanie sesji dla wiadomości
|
||||
- [Bezpieczeństwo](/gateway/security) — model dostępu i utwardzanie
|
||||
- [Groups](/pl/channels/groups) — zachowanie czatów grupowych i bramkowanie wzmianką
|
||||
- [Channel Routing](/pl/channels/channel-routing) — routing sesji dla wiadomości
|
||||
- [Security](/pl/gateway/security) — model dostępu i utwardzanie
|
||||
|
||||
@ -1,53 +1,53 @@
|
||||
---
|
||||
read_when:
|
||||
- Zmieniasz osadzone środowisko uruchomieniowe agenta lub rejestr harness agenta
|
||||
- Rejestrujesz agent harness z wbudowanego lub zaufanego pluginu
|
||||
- Musisz zrozumieć, jak plugin Codex odnosi się do providerów modeli
|
||||
- Zmieniasz osadzony runtime agenta lub rejestr harnessów
|
||||
- Rejestrujesz harness agenta z dołączonego lub zaufanego pluginu
|
||||
- Musisz zrozumieć, jak plugin Codex odnosi się do dostawców modeli
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Eksperymentalna powierzchnia SDK dla pluginów, które zastępują niskopoziomowy osadzony executor agenta
|
||||
title: Pluginy Agent Harness
|
||||
title: Pluginy Harness agenta
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:20Z"
|
||||
generated_at: "2026-04-12T00:18:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1
|
||||
source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Pluginy Agent Harness
|
||||
|
||||
**Agent harness** to niskopoziomowy executor dla jednej przygotowanej tury agenta OpenClaw. Nie jest providerem modeli, nie jest kanałem i nie jest rejestrem narzędzi.
|
||||
**Agent harness** to niskopoziomowy executor jednego przygotowanego kroku agenta OpenClaw. Nie jest dostawcą modeli, nie jest kanałem i nie jest rejestrem narzędzi.
|
||||
|
||||
Używaj tej powierzchni tylko dla wbudowanych lub zaufanych natywnych pluginów. Kontrakt jest nadal eksperymentalny, ponieważ typy parametrów celowo odzwierciedlają bieżący osadzony runner.
|
||||
Używaj tej powierzchni tylko dla dołączonych lub zaufanych natywnych pluginów. Kontrakt jest nadal eksperymentalny, ponieważ typy parametrów celowo odzwierciedlają obecny osadzony runner.
|
||||
|
||||
## Kiedy używać harness
|
||||
## Kiedy używać harnessu
|
||||
|
||||
Zarejestruj agent harness, gdy rodzina modeli ma własne natywne środowisko uruchomieniowe sesji, a zwykły transport providera OpenClaw jest niewłaściwą abstrakcją.
|
||||
Zarejestruj agent harness, gdy rodzina modeli ma własny natywny runtime sesji, a standardowy transport dostawcy OpenClaw jest niewłaściwą abstrakcją.
|
||||
|
||||
Przykłady:
|
||||
|
||||
- natywny serwer coding-agent, który zarządza wątkami i kompaktacją
|
||||
- natywny serwer coding-agent, który zarządza wątkami i kompaktowaniem
|
||||
- lokalny CLI lub demon, który musi strumieniować natywne zdarzenia planu/rozumowania/narzędzi
|
||||
- środowisko uruchomieniowe modelu, które oprócz transkryptu sesji OpenClaw potrzebuje własnego resume id
|
||||
- runtime modelu, który oprócz transkryptu sesji OpenClaw potrzebuje własnego identyfikatora wznowienia
|
||||
|
||||
**Nie** rejestruj harness tylko po to, aby dodać nowe API LLM. Dla zwykłych interfejsów modeli HTTP lub WebSocket zbuduj [provider plugin](/pl/plugins/sdk-provider-plugins).
|
||||
**Nie** rejestruj harnessu tylko po to, aby dodać nowe API LLM. Dla zwykłych modeli API HTTP lub WebSocket zbuduj [plugin dostawcy](/pl/plugins/sdk-provider-plugins).
|
||||
|
||||
## Czym nadal zarządza core
|
||||
|
||||
Zanim harness zostanie wybrany, OpenClaw już ustalił:
|
||||
Zanim harness zostanie wybrany, OpenClaw ma już rozstrzygnięte:
|
||||
|
||||
- providera i model
|
||||
- stan auth runtime
|
||||
- poziom rozumowania i budżet kontekstu
|
||||
- dostawcę i model
|
||||
- stan uwierzytelniania runtime
|
||||
- poziom myślenia i budżet kontekstu
|
||||
- plik transkryptu/sesji OpenClaw
|
||||
- workspace, sandbox i politykę narzędzi
|
||||
- callbacki odpowiedzi kanału i callbacki streamingu
|
||||
- callbacki odpowiedzi kanału i callbacki strumieniowania
|
||||
- politykę fallbacku modelu i przełączania modeli na żywo
|
||||
|
||||
Ten podział jest celowy. Harness uruchamia przygotowaną próbę; nie wybiera providerów, nie zastępuje dostarczania kanałowego i nie przełącza po cichu modeli.
|
||||
Ten podział jest celowy. Harness uruchamia przygotowaną próbę; nie wybiera dostawców, nie zastępuje dostarczania przez kanał i nie przełącza po cichu modeli.
|
||||
|
||||
## Rejestracja harness
|
||||
## Zarejestruj harness
|
||||
|
||||
**Import:** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -83,42 +83,51 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
## Zasady wyboru
|
||||
## Polityka wyboru
|
||||
|
||||
OpenClaw wybiera harness po rozstrzygnięciu providera/modelu:
|
||||
OpenClaw wybiera harness po rozstrzygnięciu dostawcy/modelu:
|
||||
|
||||
1. `OPENCLAW_AGENT_RUNTIME=<id>` wymusza zarejestrowany harness o tym id.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=pi` wymusza wbudowany harness PI.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` pyta zarejestrowane harnessy, czy obsługują rozstrzygnięty provider/model.
|
||||
4. Jeśli żaden zarejestrowany harness nie pasuje, OpenClaw używa PI, chyba że fallback PI jest wyłączony.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` pyta zarejestrowane harnessy, czy obsługują rozstrzygniętego dostawcę/model.
|
||||
4. Jeśli żaden zarejestrowany harness nie pasuje, OpenClaw używa PI, chyba że fallback do PI jest wyłączony.
|
||||
|
||||
Błędy wymuszonego plugin harness są zgłaszane jako błędy uruchomienia. W trybie `auto` OpenClaw może wrócić do PI, gdy wybrany plugin harness zakończy się błędem, zanim tura wywoła skutki uboczne. Ustaw `OPENCLAW_AGENT_HARNESS_FALLBACK=none` lub `embeddedHarness.fallback: "none"`, aby taki fallback był twardym błędem.
|
||||
Błędy wymuszonego plugin harnessu są zgłaszane jako błędy uruchomienia. W trybie `auto` OpenClaw może wrócić do PI, jeśli wybrany plugin harness zakończy się błędem, zanim krok wywoła skutki uboczne. Ustaw `OPENCLAW_AGENT_HARNESS_FALLBACK=none` lub `embeddedHarness.fallback: "none"`, aby taki fallback zamiast tego był twardym błędem.
|
||||
|
||||
Dołączony plugin Codex rejestruje `codex` jako id swojego harness. Core traktuje to jak zwykłe id plugin harness; aliasy specyficzne dla Codex powinny należeć do pluginu albo konfiguracji operatora, a nie do wspólnego selektora runtime.
|
||||
Dołączony plugin Codex rejestruje `codex` jako swoje id harnessu. Core traktuje to jak zwykłe id plugin harnessu; aliasy specyficzne dla Codex powinny należeć do pluginu lub konfiguracji operatora, a nie do współdzielonego selektora runtime.
|
||||
|
||||
## Parowanie provider plus harness
|
||||
## Parowanie dostawcy i harnessu
|
||||
|
||||
Większość harnessów powinna także rejestrować providera. Provider udostępnia odwołania do modeli, stan auth, metadane modeli i wybór `/model` pozostałej części OpenClaw. Harness następnie zgłasza tego providera w `supports(...)`.
|
||||
Większość harnessów powinna także zarejestrować dostawcę. Dostawca udostępnia reszcie OpenClaw referencje modeli, status uwierzytelnienia, metadane modeli i wybór `/model`. Następnie harness zgłasza tego dostawcę w `supports(...)`.
|
||||
|
||||
Dołączony plugin Codex stosuje ten wzorzec:
|
||||
|
||||
- id providera: `codex`
|
||||
- odwołania do modeli użytkownika: `codex/gpt-5.4`, `codex/gpt-5.2` albo inny model zwrócony przez serwer aplikacji Codex
|
||||
- id harness: `codex`
|
||||
- auth: syntetyczna dostępność providera, ponieważ harness Codex zarządza natywnym logowaniem/sesją Codex
|
||||
- żądanie app-servera: OpenClaw wysyła do Codex samo id modelu i pozwala harnessowi rozmawiać z natywnym protokołem app-servera
|
||||
- id dostawcy: `codex`
|
||||
- referencje modeli użytkownika: `codex/gpt-5.4`, `codex/gpt-5.2` lub inny model zwracany przez serwer aplikacji Codex
|
||||
- id harnessu: `codex`
|
||||
- uwierzytelnianie: syntetyczna dostępność dostawcy, ponieważ harness Codex zarządza natywnym logowaniem/sesją Codex
|
||||
- żądanie app-server: OpenClaw wysyła do Codex samo id modelu i pozwala harnessowi komunikować się z natywnym protokołem app-server
|
||||
|
||||
Plugin Codex jest dodatkiem. Zwykłe odwołania `openai/gpt-*` pozostają odwołaniami providera OpenAI i nadal używają normalnej ścieżki providera OpenClaw. Wybierz `codex/gpt-*`, gdy chcesz auth zarządzanego przez Codex, wykrywania modeli Codex, natywnych wątków i wykonywania przez app-server Codex. `/model` może przełączać się między modelami Codex zwróconymi przez serwer aplikacji Codex bez konieczności posiadania poświadczeń providera OpenAI.
|
||||
Plugin Codex jest dodatkiem. Zwykłe referencje `openai/gpt-*` pozostają referencjami dostawcy OpenAI i nadal używają standardowej ścieżki dostawcy OpenClaw. Wybierz `codex/gpt-*`, gdy chcesz uwierzytelniania zarządzanego przez Codex, wykrywania modeli Codex, natywnych wątków i wykonywania przez app-server Codex. `/model` może przełączać się między modelami Codex zwracanymi przez app-server Codex bez konieczności posiadania poświadczeń dostawcy OpenAI.
|
||||
|
||||
Informacje o konfiguracji operatora, przykłady prefiksów modeli i konfiguracje tylko dla Codex znajdziesz w [Codex Harness](/pl/plugins/codex-harness).
|
||||
|
||||
OpenClaw wymaga app-servera Codex `0.118.0` lub nowszego. Plugin Codex sprawdza handshake inicjalizacji app-servera i blokuje starsze lub niezwersjonowane serwery, aby OpenClaw działał tylko z powierzchnią protokołu, na której został przetestowany.
|
||||
OpenClaw wymaga app-server Codex w wersji `0.118.0` lub nowszej. Plugin Codex sprawdza handshake inicjalizacji app-server i blokuje starsze lub niewersjonowane serwery, aby OpenClaw działał tylko z powierzchnią protokołu, z którą był testowany.
|
||||
|
||||
## Wyłącz fallback PI
|
||||
### Tryb natywnego harnessu Codex
|
||||
|
||||
Domyślnie OpenClaw uruchamia osadzonych agentów z `agents.defaults.embeddedHarness` ustawionym na `{ runtime: "auto", fallback: "pi" }`. W trybie `auto` zarejestrowane plugin harnessy mogą przejąć parę provider/model. Jeśli żaden nie pasuje albo jeśli automatycznie wybrany plugin harness zakończy się błędem przed wygenerowaniem danych wyjściowych, OpenClaw wraca do PI.
|
||||
Dołączony harness `codex` to natywny tryb Codex dla osadzonych kroków agenta OpenClaw. Najpierw włącz dołączony plugin `codex` i uwzględnij `codex` w `plugins.allow`, jeśli twoja konfiguracja używa restrykcyjnej allowlisty. Różni się od `openai-codex/*`:
|
||||
|
||||
Ustaw `fallback: "none"`, gdy musisz udowodnić, że plugin harness jest jedynym używanym runtime. To wyłącza automatyczny fallback PI; nie blokuje jawnego `runtime: "pi"` ani `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
- `openai-codex/*` używa OAuth ChatGPT/Codex przez standardową ścieżkę dostawcy OpenClaw.
|
||||
- `codex/*` używa dołączonego dostawcy Codex i kieruje krok przez app-server Codex.
|
||||
|
||||
Gdy ten tryb działa, Codex zarządza natywnym id wątku, zachowaniem wznowienia, kompaktowaniem i wykonywaniem przez app-server. OpenClaw nadal zarządza kanałem czatu, widocznym mirrorowaniem transkryptu, polityką narzędzi, zatwierdzeniami, dostarczaniem mediów i wyborem sesji. Użyj `embeddedHarness.runtime: "codex"` z `embeddedHarness.fallback: "none"`, gdy musisz potwierdzić, że używana jest ścieżka app-server Codex, a fallback do PI nie ukrywa uszkodzonego natywnego harnessu.
|
||||
|
||||
## Wyłącz fallback do PI
|
||||
|
||||
Domyślnie OpenClaw uruchamia osadzonych agentów z `agents.defaults.embeddedHarness` ustawionym na `{ runtime: "auto", fallback: "pi" }`. W trybie `auto` zarejestrowane plugin harnessy mogą zgłaszać obsługę pary dostawca/model. Jeśli żaden nie pasuje albo jeśli automatycznie wybrany plugin harness zakończy się błędem przed wygenerowaniem wyjścia, OpenClaw wraca do PI.
|
||||
|
||||
Ustaw `fallback: "none"`, gdy musisz potwierdzić, że plugin harness jest jedynym używanym runtime. Wyłącza to automatyczny fallback do PI; nie blokuje jawnego `runtime: "pi"` ani `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Dla osadzonych uruchomień tylko z Codex:
|
||||
|
||||
@ -136,7 +145,7 @@ Dla osadzonych uruchomień tylko z Codex:
|
||||
}
|
||||
```
|
||||
|
||||
Jeśli chcesz, aby dowolny zarejestrowany plugin harness przejmował pasujące modele, ale nigdy nie chcesz, aby OpenClaw po cichu wracał do PI, pozostaw `runtime: "auto"` i wyłącz fallback:
|
||||
Jeśli chcesz, aby dowolny zarejestrowany plugin harness zgłaszał pasujące modele, ale nigdy nie chcesz, aby OpenClaw po cichu wracał do PI, pozostaw `runtime: "auto"` i wyłącz fallback:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -151,7 +160,7 @@ Jeśli chcesz, aby dowolny zarejestrowany plugin harness przejmował pasujące m
|
||||
}
|
||||
```
|
||||
|
||||
Nadpisania dla konkretnych agentów mają ten sam kształt:
|
||||
Nadpisania dla poszczególnych agentów używają tego samego kształtu:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -176,7 +185,7 @@ Nadpisania dla konkretnych agentów mają ten sam kształt:
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` nadal nadpisuje skonfigurowany runtime. Użyj `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, aby wyłączyć fallback PI z poziomu środowiska.
|
||||
`OPENCLAW_AGENT_RUNTIME` nadal nadpisuje skonfigurowany runtime. Użyj `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, aby wyłączyć fallback do PI z poziomu środowiska.
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -184,39 +193,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Przy wyłączonym fallbacku sesja kończy się błędem wcześnie, gdy żądany harness nie jest zarejestrowany, nie obsługuje rozstrzygniętego providera/modelu albo kończy się błędem przed wygenerowaniem skutków ubocznych tury. Jest to celowe dla wdrożeń tylko z Codex i dla testów live, które muszą potwierdzić, że faktycznie używana jest ścieżka app-servera Codex.
|
||||
Przy wyłączonym fallbacku sesja kończy się wcześnie błędem, gdy żądany harness nie jest zarejestrowany, nie obsługuje rozstrzygniętego dostawcy/modelu albo kończy się błędem przed wywołaniem skutków ubocznych kroku. Jest to zamierzone dla wdrożeń tylko z Codex oraz dla testów live, które muszą potwierdzić, że ścieżka app-server Codex jest rzeczywiście używana.
|
||||
|
||||
To ustawienie kontroluje tylko osadzony agent harness. Nie wyłącza routingu modeli specyficznych dla providerów dla obrazów, wideo, muzyki, TTS, PDF ani innych typów.
|
||||
To ustawienie kontroluje tylko osadzony agent harness. Nie wyłącza routingu modeli specyficznego dla dostawcy dla obrazów, wideo, muzyki, TTS, PDF ani innych funkcji.
|
||||
|
||||
## Natywne sesje i lustro transkryptu
|
||||
## Natywne sesje i mirror transkryptu
|
||||
|
||||
Harness może przechowywać natywne id sesji, id wątku albo token wznowienia po stronie demona. Powiąż to jawnie z sesją OpenClaw i nadal odzwierciedlaj widoczne dla użytkownika dane wyjściowe asystenta/narzędzi w transkrypcie OpenClaw.
|
||||
Harness może przechowywać natywne id sesji, id wątku albo token wznowienia po stronie demona. Zachowuj to powiązanie jawnie skojarzone z sesją OpenClaw i nadal mirroruj widoczne dla użytkownika wyjście asystenta/narzędzi do transkryptu OpenClaw.
|
||||
|
||||
Transkrypt OpenClaw pozostaje warstwą zgodności dla:
|
||||
Transkrypt OpenClaw pozostaje warstwą kompatybilności dla:
|
||||
|
||||
- historii sesji widocznej w kanałach
|
||||
- wyszukiwania i indeksowania transkryptów
|
||||
- późniejszego przełączenia z powrotem na wbudowany harness PI
|
||||
- historii sesji widocznej w kanale
|
||||
- wyszukiwania i indeksowania transkryptu
|
||||
- przełączenia z powrotem na wbudowany harness PI w późniejszym kroku
|
||||
- ogólnego zachowania `/new`, `/reset` i usuwania sesji
|
||||
|
||||
Jeśli harness przechowuje powiązanie sidecar, zaimplementuj `reset(...)`, aby OpenClaw mógł je wyczyścić przy resetowaniu powiązanej sesji OpenClaw.
|
||||
Jeśli twój harness przechowuje powiązanie sidecar, zaimplementuj `reset(...)`, aby OpenClaw mógł je wyczyścić, gdy powiązana sesja OpenClaw zostanie zresetowana.
|
||||
|
||||
## Wyniki narzędzi i mediów
|
||||
|
||||
Core tworzy listę narzędzi OpenClaw i przekazuje ją do przygotowanej próby. Gdy harness wykonuje dynamiczne wywołanie narzędzia, zwróć wynik narzędzia przez kształt wyniku harness zamiast samodzielnie wysyłać media kanałowe.
|
||||
Core konstruuje listę narzędzi OpenClaw i przekazuje ją do przygotowanej próby. Gdy harness wykonuje dynamiczne wywołanie narzędzia, zwróć wynik narzędzia przez kształt wyniku harnessu zamiast samodzielnie wysyłać media kanału.
|
||||
|
||||
Dzięki temu wyjścia tekstowe, obrazów, wideo, muzyki, TTS, zatwierdzeń i narzędzi wiadomości pozostają na tej samej ścieżce dostarczania co uruchomienia oparte na PI.
|
||||
Dzięki temu wyjścia tekstowe, obrazy, wideo, muzyka, TTS, zatwierdzenia i wyjścia narzędzi do komunikacji pozostają na tej samej ścieżce dostarczania co uruchomienia oparte na PI.
|
||||
|
||||
## Bieżące ograniczenia
|
||||
## Obecne ograniczenia
|
||||
|
||||
- Publiczna ścieżka importu jest ogólna, ale niektóre aliasy typów prób/wyników nadal zawierają nazwy `Pi` ze względu na zgodność.
|
||||
- Instalacja harnessów firm trzecich jest eksperymentalna. Preferuj provider pluginy, dopóki nie potrzebujesz natywnego środowiska uruchomieniowego sesji.
|
||||
- Przełączanie harnessów między turami jest obsługiwane. Nie przełączaj harnessów w środku tury po rozpoczęciu natywnych narzędzi, zatwierdzeń, tekstu asystenta lub wysyłania wiadomości.
|
||||
- Publiczna ścieżka importu jest ogólna, ale niektóre aliasy typów prób/wyników nadal zawierają nazwy `Pi` ze względu na kompatybilność.
|
||||
- Instalacja harnessów firm trzecich jest eksperymentalna. Preferuj pluginy dostawców, dopóki nie potrzebujesz natywnego runtime sesji.
|
||||
- Przełączanie harnessów między krokami jest obsługiwane. Nie przełączaj harnessów w środku kroku po rozpoczęciu natywnych narzędzi, zatwierdzeń, tekstu asystenta lub wysyłania wiadomości.
|
||||
|
||||
## Powiązane
|
||||
|
||||
- [Przegląd SDK](/pl/plugins/sdk-overview)
|
||||
- [Runtime Helpers](/pl/plugins/sdk-runtime)
|
||||
- [Provider Plugins](/pl/plugins/sdk-provider-plugins)
|
||||
- [Pomocniki runtime](/pl/plugins/sdk-runtime)
|
||||
- [Pluginy dostawców](/pl/plugins/sdk-provider-plugins)
|
||||
- [Codex Harness](/pl/plugins/codex-harness)
|
||||
- [Providery modeli](/pl/concepts/model-providers)
|
||||
- [Dostawcy modeli](/pl/concepts/model-providers)
|
||||
|
||||
@ -2,30 +2,32 @@
|
||||
read_when:
|
||||
- Chcesz używać modeli OpenAI w OpenClaw
|
||||
- Chcesz używać uwierzytelniania subskrypcją Codex zamiast kluczy API
|
||||
summary: Używanie OpenAI przez klucze API lub subskrypcję Codex w OpenClaw
|
||||
- Potrzebujesz bardziej rygorystycznego zachowania wykonywania agenta GPT-5
|
||||
summary: Używaj OpenAI za pomocą kluczy API lub subskrypcji Codex w OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:50:07Z"
|
||||
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 udostępnia API dla deweloperów dla modeli GPT. Codex obsługuje **logowanie przez ChatGPT** dla dostępu
|
||||
subskrypcyjnego lub **logowanie kluczem API** dla dostępu rozliczanego według użycia. Chmura Codex wymaga logowania przez ChatGPT.
|
||||
OpenAI jawnie wspiera użycie subskrypcyjnego OAuth w zewnętrznych narzędziach/przepływach pracy, takich jak OpenClaw.
|
||||
OpenAI udostępnia interfejsy API dla deweloperów do modeli GPT. Codex obsługuje **logowanie przez ChatGPT** dla dostępu w ramach subskrypcji
|
||||
lub logowanie za pomocą **klucza API** dla dostępu rozliczanego według użycia. Chmura Codex wymaga logowania przez ChatGPT.
|
||||
OpenAI jawnie wspiera użycie OAuth subskrypcji w zewnętrznych narzędziach/przepływach pracy, takich jak OpenClaw.
|
||||
|
||||
## Domyślny styl interakcji
|
||||
|
||||
OpenClaw może dodać małą nakładkę promptu specyficzną dla OpenAI zarówno dla uruchomień `openai/*`, jak i
|
||||
OpenClaw może dodać niewielką nakładkę promptu specyficzną dla OpenAI zarówno dla uruchomień `openai/*`, jak i
|
||||
`openai-codex/*`. Domyślnie nakładka utrzymuje asystenta jako ciepłego,
|
||||
współpracującego, zwięzłego, bezpośredniego i nieco bardziej ekspresyjnego emocjonalnie,
|
||||
nie zastępując bazowego promptu systemowego OpenClaw. Przyjazna nakładka
|
||||
pozwala też okazjonalnie użyć emoji, gdy pasuje to naturalnie, przy zachowaniu ogólnie zwięzłej odpowiedzi.
|
||||
współpracującego, zwięzłego, bezpośredniego i trochę bardziej emocjonalnie ekspresyjnego,
|
||||
bez zastępowania bazowego promptu systemowego OpenClaw. Przyjazna nakładka
|
||||
dopuszcza też okazjonalne emoji, gdy pasuje to naturalnie, przy zachowaniu ogólnej zwięzłości
|
||||
wypowiedzi.
|
||||
|
||||
Klucz konfiguracji:
|
||||
|
||||
@ -33,7 +35,7 @@ Klucz konfiguracji:
|
||||
|
||||
Dozwolone wartości:
|
||||
|
||||
- `"friendly"`: domyślne; włącza nakładkę specyficzną dla OpenAI.
|
||||
- `"friendly"`: domyślnie; włącza nakładkę specyficzną dla OpenAI.
|
||||
- `"on"`: alias dla `"friendly"`.
|
||||
- `"off"`: wyłącza nakładkę i używa tylko bazowego promptu OpenClaw.
|
||||
|
||||
@ -44,7 +46,7 @@ Zakres:
|
||||
- Nie wpływa na innych dostawców.
|
||||
|
||||
To zachowanie jest domyślnie włączone. Zachowaj jawnie `"friendly"`, jeśli chcesz,
|
||||
aby przetrwało przyszłe lokalne zmiany konfiguracji:
|
||||
aby przetrwało to przyszłe lokalne zmiany konfiguracji:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -62,7 +64,7 @@ aby przetrwało przyszłe lokalne zmiany konfiguracji:
|
||||
|
||||
### Wyłącz nakładkę promptu OpenAI
|
||||
|
||||
Jeśli chcesz niezmodyfikowanego bazowego promptu OpenClaw, ustaw nakładkę na `"off"`:
|
||||
Jeśli chcesz niezmodyfikowany bazowy prompt OpenClaw, ustaw nakładkę na `"off"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -78,25 +80,25 @@ Jeśli chcesz niezmodyfikowanego bazowego promptu OpenClaw, ustaw nakładkę na
|
||||
}
|
||||
```
|
||||
|
||||
Możesz też ustawić to bezpośrednio przez konfigurację CLI:
|
||||
Możesz też ustawić to bezpośrednio za pomocą CLI konfiguracji:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.openai.config.personality off
|
||||
```
|
||||
|
||||
OpenClaw normalizuje to ustawienie bez rozróżniania wielkości liter w czasie działania, więc wartości takie jak
|
||||
`"Off"` również wyłączą przyjazną nakładkę.
|
||||
OpenClaw normalizuje to ustawienie w czasie działania bez rozróżniania wielkości liter, więc wartości takie jak
|
||||
`"Off"` również wyłączają przyjazną nakładkę.
|
||||
|
||||
## Opcja A: klucz API OpenAI (OpenAI Platform)
|
||||
|
||||
**Najlepsze do:** bezpośredniego dostępu do API i rozliczania według użycia.
|
||||
Pobierz klucz API z panelu OpenAI.
|
||||
**Najlepsze dla:** bezpośredniego dostępu do API i rozliczania według użycia.
|
||||
Pobierz swój klucz API z panelu OpenAI.
|
||||
|
||||
Podsumowanie ścieżki:
|
||||
Podsumowanie ścieżek:
|
||||
|
||||
- `openai/gpt-5.4` = bezpośrednia ścieżka API OpenAI Platform
|
||||
- Wymaga `OPENAI_API_KEY` (lub równoważnej konfiguracji dostawcy OpenAI)
|
||||
- W OpenClaw logowanie ChatGPT/Codex jest routowane przez `openai-codex/*`, a nie `openai/*`
|
||||
- W OpenClaw logowanie ChatGPT/Codex jest kierowane przez `openai-codex/*`, a nie `openai/*`
|
||||
|
||||
### Konfiguracja CLI
|
||||
|
||||
@ -115,25 +117,26 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
}
|
||||
```
|
||||
|
||||
Aktualna dokumentacja modeli API OpenAI wymienia `gpt-5.4` i `gpt-5.4-pro` dla bezpośredniego
|
||||
Bieżąca dokumentacja modeli API OpenAI wymienia `gpt-5.4` i `gpt-5.4-pro` dla bezpośredniego
|
||||
użycia API OpenAI. OpenClaw przekazuje oba przez ścieżkę `openai/*` Responses.
|
||||
OpenClaw celowo ukrywa przestarzały wiersz `openai/gpt-5.3-codex-spark`,
|
||||
OpenClaw celowo ukrywa nieaktualny wiersz `openai/gpt-5.3-codex-spark`,
|
||||
ponieważ bezpośrednie wywołania API OpenAI odrzucają go w rzeczywistym ruchu.
|
||||
|
||||
OpenClaw **nie** udostępnia `openai/gpt-5.3-codex-spark` na bezpośredniej ścieżce API OpenAI.
|
||||
`pi-ai` nadal dostarcza wbudowany wiersz dla tego modelu, ale rzeczywiste żądania API OpenAI są obecnie odrzucane. Spark jest traktowany w OpenClaw jako wyłącznie Codex.
|
||||
OpenClaw **nie** udostępnia `openai/gpt-5.3-codex-spark` na bezpośredniej ścieżce OpenAI
|
||||
API. `pi-ai` nadal zawiera wbudowany wiersz dla tego modelu, ale rzeczywiste żądania do API OpenAI
|
||||
są obecnie odrzucane. W OpenClaw Spark jest traktowany jako dostępny tylko w Codex.
|
||||
|
||||
## Generowanie obrazów
|
||||
|
||||
Dołączona wtyczka `openai` rejestruje także generowanie obrazów przez wspólne
|
||||
Dołączona w pakiecie wtyczka `openai` rejestruje też generowanie obrazów przez współdzielone
|
||||
narzędzie `image_generate`.
|
||||
|
||||
- Domyślny model obrazu: `openai/gpt-image-1`
|
||||
- Domyślny model obrazów: `openai/gpt-image-1`
|
||||
- Generowanie: do 4 obrazów na żądanie
|
||||
- Tryb edycji: włączony, do 5 obrazów referencyjnych
|
||||
- Obsługuje `size`
|
||||
- Aktualne zastrzeżenie specyficzne dla OpenAI: OpenClaw obecnie nie przekazuje nadpisań `aspectRatio` ani
|
||||
`resolution` do OpenAI Images API
|
||||
`resolution` do API OpenAI Images
|
||||
|
||||
Aby używać OpenAI jako domyślnego dostawcy obrazów:
|
||||
|
||||
@ -149,21 +152,21 @@ Aby używać OpenAI jako domyślnego dostawcy obrazów:
|
||||
}
|
||||
```
|
||||
|
||||
Zobacz [Generowanie obrazów](/pl/tools/image-generation), aby poznać wspólne parametry
|
||||
Zobacz [Generowanie obrazów](/pl/tools/image-generation), aby poznać współdzielone parametry
|
||||
narzędzia, wybór dostawcy i zachowanie failover.
|
||||
|
||||
## Generowanie wideo
|
||||
|
||||
Dołączona wtyczka `openai` rejestruje także generowanie wideo przez wspólne
|
||||
Dołączona w pakiecie wtyczka `openai` rejestruje też generowanie wideo przez współdzielone
|
||||
narzędzie `video_generate`.
|
||||
|
||||
- Domyślny model wideo: `openai/sora-2`
|
||||
- Tryby: text-to-video, image-to-video oraz przepływy referencji/edycji pojedynczego wideo
|
||||
- Bieżące limity: 1 obraz lub 1 referencyjne wejście wideo
|
||||
- Tryby: tekst-na-wideo, obraz-na-wideo oraz przepływy referencji/edycji pojedynczego wideo
|
||||
- Obecne limity: 1 obraz lub 1 wejście referencyjne wideo
|
||||
- Aktualne zastrzeżenie specyficzne dla OpenAI: OpenClaw obecnie przekazuje tylko nadpisania `size`
|
||||
dla natywnego generowania wideo OpenAI. Nieobsługiwane opcjonalne nadpisania,
|
||||
takie jak `aspectRatio`, `resolution`, `audio` i `watermark`, są ignorowane
|
||||
i zwracane jako ostrzeżenie narzędzia.
|
||||
i zgłaszane z powrotem jako ostrzeżenie narzędzia.
|
||||
|
||||
Aby używać OpenAI jako domyślnego dostawcy wideo:
|
||||
|
||||
@ -179,19 +182,19 @@ Aby używać OpenAI jako domyślnego dostawcy wideo:
|
||||
}
|
||||
```
|
||||
|
||||
Zobacz [Generowanie wideo](/pl/tools/video-generation), aby poznać wspólne parametry
|
||||
Zobacz [Generowanie wideo](/pl/tools/video-generation), aby poznać współdzielone parametry
|
||||
narzędzia, wybór dostawcy i zachowanie failover.
|
||||
|
||||
## Opcja B: subskrypcja OpenAI Code (Codex)
|
||||
|
||||
**Najlepsze do:** używania dostępu subskrypcyjnego ChatGPT/Codex zamiast klucza API.
|
||||
Chmura Codex wymaga logowania przez ChatGPT, podczas gdy CLI Codex obsługuje logowanie przez ChatGPT lub klucz API.
|
||||
**Najlepsze dla:** używania dostępu w ramach subskrypcji ChatGPT/Codex zamiast klucza API.
|
||||
Chmura Codex wymaga logowania przez ChatGPT, natomiast CLI Codex obsługuje logowanie przez ChatGPT lub klucz API.
|
||||
|
||||
Podsumowanie ścieżki:
|
||||
Podsumowanie ścieżek:
|
||||
|
||||
- `openai-codex/gpt-5.4` = ścieżka OAuth ChatGPT/Codex
|
||||
- Używa logowania ChatGPT/Codex, a nie bezpośredniego klucza API OpenAI Platform
|
||||
- Limity po stronie dostawcy dla `openai-codex/*` mogą różnić się od doświadczenia ChatGPT w web/app
|
||||
- Limity po stronie dostawcy dla `openai-codex/*` mogą różnić się od doświadczenia w wersji webowej/aplikacji ChatGPT
|
||||
|
||||
### Konfiguracja CLI (Codex OAuth)
|
||||
|
||||
@ -211,42 +214,42 @@ openclaw models auth login --provider openai-codex
|
||||
}
|
||||
```
|
||||
|
||||
Aktualna dokumentacja Codex OpenAI wymienia `gpt-5.4` jako bieżący model Codex. OpenClaw
|
||||
mapuje go na `openai-codex/gpt-5.4` do użycia z OAuth ChatGPT/Codex.
|
||||
Bieżąca dokumentacja Codex OpenAI wymienia `gpt-5.4` jako aktualny model Codex. OpenClaw
|
||||
mapuje to na `openai-codex/gpt-5.4` dla użycia OAuth ChatGPT/Codex.
|
||||
|
||||
Ta ścieżka jest celowo oddzielona od `openai/gpt-5.4`. Jeśli chcesz
|
||||
bezpośredniej ścieżki API OpenAI Platform, użyj `openai/*` z kluczem API. Jeśli chcesz
|
||||
logowania ChatGPT/Codex, użyj `openai-codex/*`.
|
||||
|
||||
Jeśli onboarding ponownie wykorzystuje istniejące logowanie Codex CLI, te poświadczenia pozostają
|
||||
zarządzane przez Codex CLI. Po wygaśnięciu OpenClaw najpierw ponownie odczytuje zewnętrzne źródło Codex
|
||||
i, gdy dostawca może je odświeżyć, zapisuje odświeżone poświadczenie z powrotem
|
||||
do pamięci Codex zamiast przejmować je we własnej kopii tylko dla OpenClaw.
|
||||
Jeśli onboarding wykorzysta ponownie istniejące logowanie CLI Codex, te poświadczenia pozostaną
|
||||
zarządzane przez CLI Codex. Po wygaśnięciu OpenClaw najpierw ponownie odczytuje zewnętrzne źródło Codex
|
||||
i, gdy dostawca może je odświeżyć, zapisuje odświeżone poświadczenie
|
||||
z powrotem do magazynu Codex zamiast przejmować je do osobnej kopii używanej wyłącznie przez OpenClaw.
|
||||
|
||||
Jeśli Twoje konto Codex ma uprawnienia do Codex Spark, OpenClaw obsługuje również:
|
||||
|
||||
- `openai-codex/gpt-5.3-codex-spark`
|
||||
|
||||
OpenClaw traktuje Codex Spark jako wyłącznie Codex. Nie udostępnia bezpośredniej
|
||||
ścieżki klucza API `openai/gpt-5.3-codex-spark`.
|
||||
OpenClaw traktuje Codex Spark jako dostępny tylko w Codex. Nie udostępnia bezpośredniej
|
||||
ścieżki z kluczem API `openai/gpt-5.3-codex-spark`.
|
||||
|
||||
OpenClaw zachowuje również `openai-codex/gpt-5.3-codex-spark`, gdy `pi-ai`
|
||||
go wykryje. Traktuj go jako zależny od uprawnień i eksperymentalny: Codex Spark jest
|
||||
OpenClaw zachowuje też `openai-codex/gpt-5.3-codex-spark`, gdy `pi-ai`
|
||||
go wykryje. Traktuj to jako zależne od uprawnień i eksperymentalne: Codex Spark jest
|
||||
oddzielny od GPT-5.4 `/fast`, a dostępność zależy od zalogowanego konta Codex /
|
||||
ChatGPT.
|
||||
|
||||
### Limit okna kontekstu Codex
|
||||
|
||||
OpenClaw traktuje metadane modelu Codex i limit kontekstu w runtime jako oddzielne
|
||||
OpenClaw traktuje metadane modelu Codex i limit kontekstu w czasie działania jako oddzielne
|
||||
wartości.
|
||||
|
||||
Dla `openai-codex/gpt-5.4`:
|
||||
|
||||
- natywne `contextWindow`: `1050000`
|
||||
- domyślny limit `contextTokens` w runtime: `272000`
|
||||
- domyślny limit `contextTokens` w czasie działania: `272000`
|
||||
|
||||
Pozwala to zachować prawdziwe metadane modelu, przy jednoczesnym utrzymaniu mniejszego domyślnego
|
||||
okna runtime, które w praktyce ma lepsze właściwości opóźnienia i jakości.
|
||||
Pozwala to zachować zgodność metadanych modelu z prawdą, a jednocześnie utrzymać mniejsze domyślne okno działania,
|
||||
które w praktyce zapewnia lepszą latencję i jakość.
|
||||
|
||||
Jeśli chcesz innego efektywnego limitu, ustaw `models.providers.<provider>.models[].contextTokens`:
|
||||
|
||||
@ -268,34 +271,34 @@ Jeśli chcesz innego efektywnego limitu, ustaw `models.providers.<provider>.mode
|
||||
```
|
||||
|
||||
Używaj `contextWindow` tylko wtedy, gdy deklarujesz lub nadpisujesz natywne metadane modelu.
|
||||
Używaj `contextTokens`, gdy chcesz ograniczyć budżet kontekstu w runtime.
|
||||
Używaj `contextTokens`, gdy chcesz ograniczyć budżet kontekstu w czasie działania.
|
||||
|
||||
### Domyślny transport
|
||||
|
||||
OpenClaw używa `pi-ai` do strumieniowania modeli. Dla `openai/*` i
|
||||
`openai-codex/*` domyślnym transportem jest `"auto"` (najpierw WebSocket, potem fallback do SSE).
|
||||
OpenClaw używa `pi-ai` do strumieniowania modeli. Dla obu `openai/*` i
|
||||
`openai-codex/*` domyślnym transportem jest `"auto"` (najpierw WebSocket, potem fallback
|
||||
do SSE).
|
||||
|
||||
W trybie `"auto"` OpenClaw wykonuje również jedną ponowną próbę po wczesnej, możliwej do ponowienia awarii WebSocket,
|
||||
zanim przełączy się na SSE. Wymuszony tryb `"websocket"` nadal bezpośrednio pokazuje błędy transportu
|
||||
W trybie `"auto"` OpenClaw wykonuje też jedną ponowną próbę po wczesnej, możliwej do ponowienia awarii WebSocket,
|
||||
zanim przełączy się na SSE. Wymuszony tryb `"websocket"` nadal pokazuje błędy transportu bezpośrednio,
|
||||
zamiast ukrywać je za fallbackiem.
|
||||
|
||||
Po błędzie WebSocket przy połączeniu lub na początku tury w trybie `"auto"` OpenClaw oznacza
|
||||
ścieżkę WebSocket tej sesji jako zdegradowaną na około 60 sekund i wysyła
|
||||
kolejne tury przez SSE podczas tego cooldownu zamiast przełączać się chaotycznie między
|
||||
Po błędzie połączenia lub błędzie WebSocket na początku tury w trybie `"auto"` OpenClaw oznacza
|
||||
ścieżkę WebSocket tej sesji jako pogorszoną na około 60 sekund i wysyła
|
||||
kolejne tury przez SSE w czasie schłodzenia, zamiast bez końca przełączać się między
|
||||
transportami.
|
||||
|
||||
Dla natywnych punktów końcowych rodziny OpenAI (`openai/*`, `openai-codex/*` i Azure
|
||||
OpenAI Responses) OpenClaw dołącza też stabilny stan tożsamości sesji i tury
|
||||
do żądań, aby ponowne próby, ponowne połączenia i fallback do SSE pozostawały wyrównane do tej samej
|
||||
tożsamości rozmowy. Na natywnych ścieżkach rodziny OpenAI obejmuje to stabilne nagłówki tożsamości żądania sesji/tury oraz pasujące metadane transportu.
|
||||
OpenAI Responses) OpenClaw dołącza również stabilny stan tożsamości sesji i tury
|
||||
do żądań, aby ponowienia, ponowne połączenia i fallback do SSE pozostawały przypisane do tej samej
|
||||
tożsamości konwersacji. W natywnych ścieżkach rodziny OpenAI obejmuje to stabilne nagłówki tożsamości żądania sesji/tury oraz pasujące metadane transportu.
|
||||
|
||||
OpenClaw normalizuje również liczniki użycia OpenAI między wariantami transportu, zanim
|
||||
OpenClaw normalizuje też liczniki użycia OpenAI między wariantami transportu, zanim
|
||||
trafią one do powierzchni sesji/statusu. Natywny ruch OpenAI/Codex Responses może
|
||||
raportować użycie jako `input_tokens` / `output_tokens` albo
|
||||
`prompt_tokens` / `completion_tokens`; OpenClaw traktuje je jako te same liczniki wejścia
|
||||
i wyjścia dla `/status`, `/usage` i logów sesji. Gdy natywny ruch WebSocket pomija `total_tokens`
|
||||
(lub raportuje `0`), OpenClaw przełącza się na znormalizowaną sumę wejścia + wyjścia,
|
||||
aby widoki sesji/statusu pozostały wypełnione.
|
||||
(lub raportuje `0`), OpenClaw wraca do znormalizowanej sumy wejścia i wyjścia, aby wyświetlanie sesji/statusu pozostało wypełnione.
|
||||
|
||||
Możesz ustawić `agents.defaults.models.<provider/model>.params.transport`:
|
||||
|
||||
@ -303,8 +306,7 @@ Możesz ustawić `agents.defaults.models.<provider/model>.params.transport`:
|
||||
- `"websocket"`: wymuś WebSocket
|
||||
- `"auto"`: najpierw spróbuj WebSocket, potem fallback do SSE
|
||||
|
||||
Dla `openai/*` (Responses API) OpenClaw domyślnie włącza również rozgrzewanie WebSocket
|
||||
(`openaiWsWarmup: true`), gdy używany jest transport WebSocket.
|
||||
Dla `openai/*` (Responses API) OpenClaw domyślnie włącza też rozgrzewkę WebSocket (`openaiWsWarmup: true`), gdy używany jest transport WebSocket.
|
||||
|
||||
Powiązana dokumentacja OpenAI:
|
||||
|
||||
@ -328,12 +330,12 @@ Powiązana dokumentacja OpenAI:
|
||||
}
|
||||
```
|
||||
|
||||
### Rozgrzewanie OpenAI WebSocket
|
||||
### Rozgrzewka OpenAI WebSocket
|
||||
|
||||
Dokumentacja OpenAI opisuje rozgrzewanie jako opcjonalne. OpenClaw domyślnie je włącza dla
|
||||
`openai/*`, aby zmniejszyć opóźnienie pierwszej tury przy użyciu transportu WebSocket.
|
||||
Dokumentacja OpenAI opisuje rozgrzewkę jako opcjonalną. OpenClaw domyślnie ją włącza dla
|
||||
`openai/*`, aby skrócić opóźnienie pierwszej tury przy użyciu transportu WebSocket.
|
||||
|
||||
### Wyłącz rozgrzewanie
|
||||
### Wyłącz rozgrzewkę
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -351,7 +353,7 @@ Dokumentacja OpenAI opisuje rozgrzewanie jako opcjonalne. OpenClaw domyślnie je
|
||||
}
|
||||
```
|
||||
|
||||
### Jawnie włącz rozgrzewanie
|
||||
### Włącz rozgrzewkę jawnie
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -369,7 +371,7 @@ Dokumentacja OpenAI opisuje rozgrzewanie jako opcjonalne. OpenClaw domyślnie je
|
||||
}
|
||||
```
|
||||
|
||||
### OpenAI i priorytetowe przetwarzanie Codex
|
||||
### Priorytetowe przetwarzanie OpenAI i Codex
|
||||
|
||||
API OpenAI udostępnia priorytetowe przetwarzanie przez `service_tier=priority`. W
|
||||
OpenClaw ustaw `agents.defaults.models["<provider>/<model>"].params.serviceTier`,
|
||||
@ -406,27 +408,27 @@ Ważne zachowanie:
|
||||
|
||||
- bezpośrednie `openai/*` musi wskazywać na `api.openai.com`
|
||||
- `openai-codex/*` musi wskazywać na `chatgpt.com/backend-api`
|
||||
- jeśli kierujesz któregokolwiek dostawcę przez inny base URL lub proxy, OpenClaw pozostawia `service_tier` bez zmian
|
||||
- jeśli kierujesz któregokolwiek dostawcę przez inny podstawowy URL lub proxy, OpenClaw pozostawia `service_tier` bez zmian
|
||||
|
||||
### Tryb szybki OpenAI
|
||||
### Tryb fast OpenAI
|
||||
|
||||
OpenClaw udostępnia wspólny przełącznik trybu szybkiego dla sesji `openai/*` i
|
||||
OpenClaw udostępnia współdzielony przełącznik trybu fast zarówno dla sesji `openai/*`, jak i
|
||||
`openai-codex/*`:
|
||||
|
||||
- Czat/UI: `/fast status|on|off`
|
||||
- Konfiguracja: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Gdy tryb szybki jest włączony, OpenClaw mapuje go na priorytetowe przetwarzanie OpenAI:
|
||||
Gdy tryb fast jest włączony, OpenClaw mapuje go na priorytetowe przetwarzanie OpenAI:
|
||||
|
||||
- bezpośrednie wywołania Responses `openai/*` do `api.openai.com` wysyłają `service_tier = "priority"`
|
||||
- wywołania Responses `openai-codex/*` do `chatgpt.com/backend-api` również wysyłają `service_tier = "priority"`
|
||||
- istniejące wartości `service_tier` w ładunku są zachowywane
|
||||
- tryb szybki nie przepisuje `reasoning` ani `text.verbosity`
|
||||
- istniejące wartości `service_tier` w payloadzie są zachowywane
|
||||
- tryb fast nie nadpisuje `reasoning` ani `text.verbosity`
|
||||
|
||||
W szczególności dla GPT 5.4 najczęstsza konfiguracja to:
|
||||
Dla GPT 5.4 w szczególności najczęstsza konfiguracja to:
|
||||
|
||||
- wyślij `/fast on` w sesji używającej `openai/gpt-5.4` lub `openai-codex/gpt-5.4`
|
||||
- albo ustaw `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- wysłanie `/fast on` w sesji używającej `openai/gpt-5.4` lub `openai-codex/gpt-5.4`
|
||||
- albo ustawienie `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- jeśli używasz też OAuth Codex, ustaw również `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true`
|
||||
|
||||
Przykład:
|
||||
@ -453,45 +455,72 @@ Przykład:
|
||||
```
|
||||
|
||||
Nadpisania sesji mają pierwszeństwo przed konfiguracją. Wyczyszczenie nadpisania sesji w interfejsie Sessions UI
|
||||
przywraca sesję do skonfigurowanej wartości domyślnej.
|
||||
przywraca w sesji domyślną wartość skonfigurowaną.
|
||||
|
||||
### Natywne OpenAI a ścieżki zgodne z OpenAI
|
||||
|
||||
OpenClaw traktuje bezpośrednie punkty końcowe OpenAI, Codex i Azure OpenAI inaczej
|
||||
niż generyczne proxy `/v1` zgodne z OpenAI:
|
||||
niż ogólne proxy `/v1` zgodne z OpenAI:
|
||||
|
||||
- natywne ścieżki `openai/*`, `openai-codex/*` i Azure OpenAI zachowują
|
||||
`reasoning: { effort: "none" }`, gdy jawnie wyłączysz reasoning
|
||||
- natywne ścieżki rodziny OpenAI domyślnie ustawiają schematy narzędzi w trybie strict
|
||||
`reasoning: { effort: "none" }` bez zmian, gdy jawnie wyłączysz rozumowanie
|
||||
- natywne ścieżki z rodziny OpenAI domyślnie ustawiają schematy narzędzi w trybie ścisłym
|
||||
- ukryte nagłówki atrybucji OpenClaw (`originator`, `version` i
|
||||
`User-Agent`) są dołączane tylko na zweryfikowanych natywnych hostach OpenAI
|
||||
(`api.openai.com`) i natywnych hostach Codex (`chatgpt.com/backend-api`)
|
||||
`User-Agent`) są dołączane tylko do zweryfikowanych natywnych hostów OpenAI
|
||||
(`api.openai.com`) i natywnych hostów Codex (`chatgpt.com/backend-api`)
|
||||
- natywne ścieżki OpenAI/Codex zachowują kształtowanie żądań specyficzne dla OpenAI, takie jak
|
||||
`service_tier`, Responses `store`, ładunki zgodności reasoning OpenAI oraz
|
||||
podpowiedzi cache promptów
|
||||
- ścieżki zgodne z OpenAI w stylu proxy zachowują luźniejsze zachowanie zgodności i nie
|
||||
wymuszają ścisłych schematów narzędzi, kształtowania żądań tylko dla natywnych tras ani ukrytych
|
||||
`service_tier`, Responses `store`, payloady zgodności z rozumowaniem OpenAI oraz
|
||||
wskazówki pamięci podręcznej promptów
|
||||
- ścieżki w stylu proxy zgodne z OpenAI zachowują luźniejsze zachowanie zgodności i nie
|
||||
wymuszają ścisłych schematów narzędzi, kształtowania żądań tylko dla ścieżek natywnych ani ukrytych
|
||||
nagłówków atrybucji OpenAI/Codex
|
||||
|
||||
Azure OpenAI pozostaje w koszyku routingu natywnego pod względem transportu i zachowania zgodności,
|
||||
Azure OpenAI pozostaje w koszyku routingu natywnego pod względem zachowania transportu i zgodności,
|
||||
ale nie otrzymuje ukrytych nagłówków atrybucji OpenAI/Codex.
|
||||
|
||||
Pozwala to zachować obecne natywne zachowanie OpenAI Responses bez narzucania starszych
|
||||
shimów zgodnych z OpenAI na backendy `/v1` innych firm.
|
||||
Pozwala to zachować obecne natywne zachowanie OpenAI Responses bez wymuszania starszych
|
||||
warstw zgodności z OpenAI na backendach `/v1` innych firm.
|
||||
|
||||
### Ścisły agentowy tryb GPT
|
||||
|
||||
Dla uruchomień rodziny GPT-5 w `openai/*` i `openai-codex/*` OpenClaw może używać
|
||||
bardziej rygorystycznego osadzonego kontraktu wykonania Pi:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
embeddedPi: {
|
||||
executionContract: "strict-agentic",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Przy `strict-agentic` OpenClaw nie traktuje już tury asystenta zawierającej tylko planu jako
|
||||
udanego postępu, gdy dostępne jest konkretne działanie narzędzia. Powtarza
|
||||
turę z ukierunkowaniem na działanie natychmiast, automatycznie włącza
|
||||
ustrukturyzowane narzędzie `update_plan` dla istotnej pracy i pokazuje jawny stan blokady,
|
||||
jeśli model nadal planuje bez działania.
|
||||
|
||||
Ten tryb jest ograniczony do uruchomień rodziny GPT-5 w OpenAI i OpenAI Codex. Inni dostawcy
|
||||
i starsze rodziny modeli zachowują domyślne zachowanie osadzonego Pi, chyba że jawnie włączysz
|
||||
dla nich inne ustawienia czasu działania.
|
||||
|
||||
### Kompaktowanie po stronie serwera OpenAI Responses
|
||||
|
||||
Dla bezpośrednich modeli OpenAI Responses (`openai/*` używających `api: "openai-responses"` z
|
||||
`baseUrl` na `api.openai.com`) OpenClaw teraz automatycznie włącza wskazówki ładunku
|
||||
`baseUrl` ustawionym na `api.openai.com`) OpenClaw teraz automatycznie włącza wskazówki payloadu
|
||||
kompaktowania po stronie serwera OpenAI:
|
||||
|
||||
- Wymusza `store: true` (chyba że zgodność modelu ustawia `supportsStore: false`)
|
||||
- Wstrzykuje `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
|
||||
Domyślnie `compact_threshold` wynosi `70%` modelowego `contextWindow` (lub `80000`,
|
||||
gdy nie jest dostępne).
|
||||
Domyślnie `compact_threshold` wynosi `70%` wartości `contextWindow` modelu (lub `80000`,
|
||||
gdy jest niedostępna).
|
||||
|
||||
### Jawnie włącz kompaktowanie po stronie serwera
|
||||
### Jawne włączenie kompaktowania po stronie serwera
|
||||
|
||||
Użyj tego, gdy chcesz wymusić wstrzykiwanie `context_management` w zgodnych
|
||||
modelach Responses (na przykład Azure OpenAI Responses):
|
||||
@ -512,7 +541,7 @@ modelach Responses (na przykład Azure OpenAI Responses):
|
||||
}
|
||||
```
|
||||
|
||||
### Włącz z niestandardowym progiem
|
||||
### Włączenie z niestandardowym progiem
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -531,7 +560,7 @@ modelach Responses (na przykład Azure OpenAI Responses):
|
||||
}
|
||||
```
|
||||
|
||||
### Wyłącz kompaktowanie po stronie serwera
|
||||
### Wyłączenie kompaktowania po stronie serwera
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -555,5 +584,5 @@ Bezpośrednie modele OpenAI Responses nadal wymuszają `store: true`, chyba że
|
||||
|
||||
## Uwagi
|
||||
|
||||
- Referencje modeli zawsze używają `provider/model` (zobacz [/concepts/models](/pl/concepts/models)).
|
||||
- Szczegóły uwierzytelniania + reguły ponownego użycia znajdują się w [/concepts/oauth](/pl/concepts/oauth).
|
||||
- Odwołania do modeli zawsze używają `provider/model` (zobacz [/concepts/models](/pl/concepts/models)).
|
||||
- Szczegóły uwierzytelniania i reguły ponownego użycia znajdują się w [/concepts/oauth](/pl/concepts/oauth).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user