chore(i18n): refresh id translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
e2ee913ffe
commit
e6bc30195e
@ -1,30 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Mengerjakan fitur channel Microsoft Teams
|
||||
summary: Status dukungan bot Microsoft Teams, kapabilitas, dan konfigurasi
|
||||
- Mengerjakan fitur saluran Microsoft Teams
|
||||
summary: Status dukungan, kemampuan, dan konfigurasi bot Microsoft Teams
|
||||
title: Microsoft Teams
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:44:53Z"
|
||||
generated_at: "2026-04-12T00:18:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf
|
||||
source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79
|
||||
source_path: channels/msteams.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Microsoft Teams
|
||||
|
||||
> "Tinggalkan semua harapan, hai kalian yang masuk ke sini."
|
||||
> "Tinggalkan segala harapan, wahai kalian yang masuk ke sini."
|
||||
|
||||
Diperbarui: 2026-01-21
|
||||
Diperbarui: 2026-03-25
|
||||
|
||||
Status: teks + lampiran DM didukung; pengiriman file channel/grup memerlukan `sharePointSiteId` + izin Graph (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)). Poll dikirim melalui Adaptive Cards. Aksi pesan mengekspos `upload-file` secara eksplisit untuk pengiriman yang mengutamakan file.
|
||||
Status: teks + lampiran DM didukung; pengiriman file saluran/grup memerlukan `sharePointSiteId` + izin Graph (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)). Polls dikirim melalui Adaptive Cards. Tindakan pesan mengekspos `upload-file` yang eksplisit untuk pengiriman yang mengutamakan file.
|
||||
|
||||
## Plugin bawaan
|
||||
|
||||
Microsoft Teams dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi tidak diperlukan instalasi terpisah dalam build paket normal.
|
||||
Microsoft Teams dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi
|
||||
tidak diperlukan instalasi terpisah pada build paket normal.
|
||||
|
||||
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Teams bawaan, instal secara manual:
|
||||
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Teams bawaan,
|
||||
instal secara manual:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/msteams
|
||||
@ -36,19 +38,19 @@ Checkout lokal (saat berjalan dari repo git):
|
||||
openclaw plugins install ./path/to/local/msteams-plugin
|
||||
```
|
||||
|
||||
Detail: [Plugins](/tools/plugin)
|
||||
Detail: [Plugins](/id/tools/plugin)
|
||||
|
||||
## Penyiapan cepat (pemula)
|
||||
|
||||
1. Pastikan plugin Microsoft Teams tersedia.
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya.
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya secara bawaan.
|
||||
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
|
||||
2. Buat **Azure Bot** (App ID + client secret + tenant ID).
|
||||
3. Konfigurasikan OpenClaw dengan kredensial tersebut.
|
||||
4. Ekspos `/api/messages` (default port 3978) melalui URL publik atau tunnel.
|
||||
4. Ekspos `/api/messages` (port 3978 secara default) melalui URL publik atau tunnel.
|
||||
5. Instal paket aplikasi Teams dan jalankan gateway.
|
||||
|
||||
Config minimal:
|
||||
Konfigurasi minimal (client secret):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -64,17 +66,19 @@ Config minimal:
|
||||
}
|
||||
```
|
||||
|
||||
Catatan: obrolan grup diblokir secara default (`channels.msteams.groupPolicy: "allowlist"`). Untuk mengizinkan balasan grup, atur `channels.msteams.groupAllowFrom` (atau gunakan `groupPolicy: "open"` untuk mengizinkan anggota mana pun, dengan gating mention).
|
||||
Untuk deployment produksi, pertimbangkan menggunakan [autentikasi federasi](#federated-authentication-certificate--managed-identity) (sertifikat atau managed identity) alih-alih client secret.
|
||||
|
||||
Catatan: obrolan grup diblokir secara default (`channels.msteams.groupPolicy: "allowlist"`). Untuk mengizinkan balasan grup, setel `channels.msteams.groupAllowFrom` (atau gunakan `groupPolicy: "open"` untuk mengizinkan anggota mana pun, dengan gerbang mention).
|
||||
|
||||
## Tujuan
|
||||
|
||||
- Berbicara dengan OpenClaw melalui DM, obrolan grup, atau channel Teams.
|
||||
- Menjaga perutean tetap deterministik: balasan selalu kembali ke channel asal kedatangannya.
|
||||
- Default ke perilaku channel yang aman (mention diwajibkan kecuali dikonfigurasi lain).
|
||||
- Berbicara dengan OpenClaw melalui DM Teams, obrolan grup, atau saluran.
|
||||
- Menjaga perutean tetap deterministik: balasan selalu kembali ke saluran tempat pesan datang.
|
||||
- Menggunakan perilaku saluran yang aman secara default (mention wajib kecuali dikonfigurasi sebaliknya).
|
||||
|
||||
## Penulisan config
|
||||
## Penulisan konfigurasi
|
||||
|
||||
Secara default, Microsoft Teams diizinkan menulis pembaruan config yang dipicu oleh `/config set|unset` (memerlukan `commands.config: true`).
|
||||
Secara default, Microsoft Teams diizinkan menulis pembaruan konfigurasi yang dipicu oleh `/config set|unset` (memerlukan `commands.config: true`).
|
||||
|
||||
Nonaktifkan dengan:
|
||||
|
||||
@ -89,16 +93,16 @@ Nonaktifkan dengan:
|
||||
**Akses DM**
|
||||
|
||||
- Default: `channels.msteams.dmPolicy = "pairing"`. Pengirim yang tidak dikenal diabaikan sampai disetujui.
|
||||
- `channels.msteams.allowFrom` sebaiknya menggunakan AAD object ID yang stabil.
|
||||
- `channels.msteams.allowFrom` sebaiknya menggunakan ID objek AAD yang stabil.
|
||||
- UPN/nama tampilan dapat berubah; pencocokan langsung dinonaktifkan secara default dan hanya diaktifkan dengan `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- Wizard dapat me-resolve nama ke ID melalui Microsoft Graph jika kredensial mengizinkan.
|
||||
- Wizard dapat menyelesaikan nama menjadi ID melalui Microsoft Graph jika kredensial mengizinkan.
|
||||
|
||||
**Akses grup**
|
||||
|
||||
- Default: `channels.msteams.groupPolicy = "allowlist"` (diblokir kecuali Anda menambahkan `groupAllowFrom`). Gunakan `channels.defaults.groupPolicy` untuk menimpa default saat tidak disetel.
|
||||
- `channels.msteams.groupAllowFrom` mengontrol pengirim mana yang dapat memicu di obrolan grup/channel (fallback ke `channels.msteams.allowFrom`).
|
||||
- Set `groupPolicy: "open"` untuk mengizinkan anggota mana pun (tetap di-gate oleh mention secara default).
|
||||
- Untuk mengizinkan **tanpa channel apa pun**, set `channels.msteams.groupPolicy: "disabled"`.
|
||||
- Default: `channels.msteams.groupPolicy = "allowlist"` (diblokir kecuali Anda menambahkan `groupAllowFrom`). Gunakan `channels.defaults.groupPolicy` untuk mengganti default saat tidak disetel.
|
||||
- `channels.msteams.groupAllowFrom` mengontrol pengirim mana yang dapat memicu di obrolan grup/saluran (fallback ke `channels.msteams.allowFrom`).
|
||||
- Setel `groupPolicy: "open"` untuk mengizinkan anggota mana pun (tetap dengan gerbang mention secara default).
|
||||
- Untuk mengizinkan **tidak ada saluran**, setel `channels.msteams.groupPolicy: "disabled"`.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -113,14 +117,14 @@ Contoh:
|
||||
}
|
||||
```
|
||||
|
||||
**Teams + allowlist channel**
|
||||
**Allowlist Teams + saluran**
|
||||
|
||||
- Lingkupi balasan grup/channel dengan mendaftarkan team dan channel di bawah `channels.msteams.teams`.
|
||||
- Kunci sebaiknya menggunakan team ID yang stabil dan channel conversation ID.
|
||||
- Saat `groupPolicy="allowlist"` dan allowlist teams tersedia, hanya team/channel yang terdaftar yang diterima (dengan gating mention).
|
||||
- Batasi balasan grup/saluran dengan mencantumkan teams dan saluran di bawah `channels.msteams.teams`.
|
||||
- Kunci sebaiknya menggunakan ID team yang stabil dan ID percakapan saluran.
|
||||
- Saat `groupPolicy="allowlist"` dan allowlist teams tersedia, hanya teams/saluran yang tercantum yang diterima (dengan gerbang mention).
|
||||
- Wizard konfigurasi menerima entri `Team/Channel` dan menyimpannya untuk Anda.
|
||||
- Saat startup, OpenClaw me-resolve nama team/channel dan nama allowlist pengguna ke ID (saat izin Graph mengizinkan)
|
||||
dan mencatat pemetaannya; nama team/channel yang tidak ter-resolve tetap disimpan seperti diketik tetapi diabaikan untuk perutean secara default kecuali `channels.msteams.dangerouslyAllowNameMatching: true` diaktifkan.
|
||||
- Saat startup, OpenClaw menyelesaikan nama team/saluran dan nama pengguna pada allowlist menjadi ID (jika izin Graph mengizinkan)
|
||||
dan mencatat pemetaannya; nama team/saluran yang tidak terselesaikan tetap disimpan seperti yang diketik tetapi diabaikan untuk perutean secara default kecuali `channels.msteams.dangerouslyAllowNameMatching: true` diaktifkan.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -144,13 +148,13 @@ Contoh:
|
||||
## Cara kerjanya
|
||||
|
||||
1. Pastikan plugin Microsoft Teams tersedia.
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya.
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya secara bawaan.
|
||||
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
|
||||
2. Buat **Azure Bot** (App ID + secret + tenant ID).
|
||||
3. Bangun **paket aplikasi Teams** yang merujuk ke bot dan menyertakan izin RSC di bawah ini.
|
||||
3. Bangun **paket aplikasi Teams** yang mereferensikan bot dan menyertakan izin RSC di bawah ini.
|
||||
4. Unggah/instal aplikasi Teams ke dalam team (atau cakupan personal untuk DM).
|
||||
5. Konfigurasikan `msteams` di `~/.openclaw/openclaw.json` (atau env vars) dan jalankan gateway.
|
||||
6. Gateway mendengarkan traffic webhook Bot Framework di `/api/messages` secara default.
|
||||
6. Gateway mendengarkan lalu lintas webhook Bot Framework pada `/api/messages` secara default.
|
||||
|
||||
## Penyiapan Azure Bot (Prasyarat)
|
||||
|
||||
@ -161,16 +165,16 @@ Sebelum mengonfigurasi OpenClaw, Anda perlu membuat resource Azure Bot.
|
||||
1. Buka [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
|
||||
2. Isi tab **Basics**:
|
||||
|
||||
| Field | Value |
|
||||
| ------------------ | -------------------------------------------------------- |
|
||||
| **Bot handle** | Nama bot Anda, mis. `openclaw-msteams` (harus unik) |
|
||||
| **Subscription** | Pilih subscription Azure Anda |
|
||||
| **Resource group** | Buat baru atau gunakan yang sudah ada |
|
||||
| **Pricing tier** | **Free** untuk dev/testing |
|
||||
| **Type of App** | **Single Tenant** (disarankan - lihat catatan di bawah) |
|
||||
| **Creation type** | **Create new Microsoft App ID** |
|
||||
| Field | Value |
|
||||
| ------------------ | ---------------------------------------------------------------- |
|
||||
| **Bot handle** | Nama bot Anda, misalnya `openclaw-msteams` (harus unik) |
|
||||
| **Subscription** | Pilih langganan Azure Anda |
|
||||
| **Resource group** | Buat baru atau gunakan yang sudah ada |
|
||||
| **Pricing tier** | **Free** untuk dev/pengujian |
|
||||
| **Type of App** | **Single Tenant** (disarankan - lihat catatan di bawah) |
|
||||
| **Creation type** | **Create new Microsoft App ID** |
|
||||
|
||||
> **Pemberitahuan deprecation:** Pembuatan bot multi-tenant baru tidak lagi didukung setelah 2025-07-31. Gunakan **Single Tenant** untuk bot baru.
|
||||
> **Pemberitahuan deprecasi:** Pembuatan bot multi-tenant baru telah deprecated setelah 2025-07-31. Gunakan **Single Tenant** untuk bot baru.
|
||||
|
||||
3. Klik **Review + create** → **Create** (tunggu ~1-2 menit)
|
||||
|
||||
@ -182,18 +186,160 @@ Sebelum mengonfigurasi OpenClaw, Anda perlu membuat resource Azure Bot.
|
||||
4. Di bawah **Certificates & secrets** → **New client secret** → salin **Value** → ini adalah `appPassword` Anda
|
||||
5. Buka **Overview** → salin **Directory (tenant) ID** → ini adalah `tenantId` Anda
|
||||
|
||||
### Langkah 3: Konfigurasikan Messaging Endpoint
|
||||
### Langkah 3: Konfigurasikan Endpoint Pesan
|
||||
|
||||
1. Di Azure Bot → **Configuration**
|
||||
2. Set **Messaging endpoint** ke URL webhook Anda:
|
||||
2. Setel **Messaging endpoint** ke URL webhook Anda:
|
||||
- Produksi: `https://your-domain.com/api/messages`
|
||||
- Dev lokal: gunakan tunnel (lihat [Pengembangan Lokal](#local-development-tunneling) di bawah)
|
||||
- Dev lokal: Gunakan tunnel (lihat [Pengembangan Lokal](#local-development-tunneling) di bawah)
|
||||
|
||||
### Langkah 4: Aktifkan Channel Teams
|
||||
### Langkah 4: Aktifkan Saluran Teams
|
||||
|
||||
1. Di Azure Bot → **Channels**
|
||||
2. Klik **Microsoft Teams** → Configure → Save
|
||||
3. Terima Terms of Service
|
||||
3. Setujui Terms of Service
|
||||
|
||||
## Autentikasi Federasi (Sertifikat + Managed Identity)
|
||||
|
||||
> Ditambahkan pada 2026.3.24
|
||||
|
||||
Untuk deployment produksi, OpenClaw mendukung **autentikasi federasi** sebagai alternatif yang lebih aman dibandingkan client secret. Tersedia dua metode:
|
||||
|
||||
### Opsi A: Autentikasi berbasis sertifikat
|
||||
|
||||
Gunakan sertifikat PEM yang terdaftar pada app registration Entra ID Anda.
|
||||
|
||||
**Penyiapan:**
|
||||
|
||||
1. Buat atau dapatkan sertifikat (format PEM dengan private key).
|
||||
2. Di Entra ID → App Registration → **Certificates & secrets** → **Certificates** → unggah sertifikat publik.
|
||||
|
||||
**Konfigurasi:**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
certificatePath: "/path/to/cert.pem",
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Env vars:**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem`
|
||||
|
||||
### Opsi B: Azure Managed Identity
|
||||
|
||||
Gunakan Azure Managed Identity untuk autentikasi tanpa kata sandi. Ini ideal untuk deployment pada infrastruktur Azure (AKS, App Service, Azure VM) yang memiliki managed identity.
|
||||
|
||||
**Cara kerjanya:**
|
||||
|
||||
1. Pod/VM bot memiliki managed identity (system-assigned atau user-assigned).
|
||||
2. Sebuah **federated identity credential** menautkan managed identity ke app registration Entra ID.
|
||||
3. Saat runtime, OpenClaw menggunakan `@azure/identity` untuk memperoleh token dari endpoint Azure IMDS (`169.254.169.254`).
|
||||
4. Token diteruskan ke SDK Teams untuk autentikasi bot.
|
||||
|
||||
**Prasyarat:**
|
||||
|
||||
- Infrastruktur Azure dengan managed identity diaktifkan (AKS workload identity, App Service, VM)
|
||||
- Federated identity credential dibuat pada app registration Entra ID
|
||||
- Akses jaringan ke IMDS (`169.254.169.254:80`) dari pod/VM
|
||||
|
||||
**Konfigurasi (system-assigned managed identity):**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
useManagedIdentity: true,
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Konfigurasi (user-assigned managed identity):**
|
||||
|
||||
```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" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Env vars:**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY=true`
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>` (hanya untuk user-assigned)
|
||||
|
||||
### Penyiapan AKS Workload Identity
|
||||
|
||||
Untuk deployment AKS yang menggunakan workload identity:
|
||||
|
||||
1. **Aktifkan workload identity** pada cluster AKS Anda.
|
||||
2. **Buat federated identity credential** pada app registration 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. **Tambahkan anotasi pada service account Kubernetes** dengan app client ID:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: my-bot-sa
|
||||
annotations:
|
||||
azure.workload.identity/client-id: "<APP_CLIENT_ID>"
|
||||
```
|
||||
|
||||
4. **Tambahkan label pada pod** untuk injeksi workload identity:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
labels:
|
||||
azure.workload.identity/use: "true"
|
||||
```
|
||||
|
||||
5. **Pastikan akses jaringan** ke IMDS (`169.254.169.254`) — jika menggunakan NetworkPolicy, tambahkan aturan egress yang mengizinkan lalu lintas ke `169.254.169.254/32` pada port 80.
|
||||
|
||||
### Perbandingan jenis autentikasi
|
||||
|
||||
| Method | Config | Pros | Cons |
|
||||
| -------------------- | ---------------------------------------------- | ------------------------------------- | ---------------------------------------- |
|
||||
| **Client secret** | `appPassword` | Penyiapan sederhana | Perlu rotasi secret, kurang aman |
|
||||
| **Certificate** | `authType: "federated"` + `certificatePath` | Tidak ada shared secret di jaringan | Ada beban pengelolaan sertifikat |
|
||||
| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | Tanpa kata sandi, tidak perlu kelola secret | Memerlukan infrastruktur Azure |
|
||||
|
||||
**Perilaku default:** Saat `authType` tidak disetel, OpenClaw secara default menggunakan autentikasi client secret. Konfigurasi yang ada tetap berfungsi tanpa perubahan.
|
||||
|
||||
## Pengembangan Lokal (Tunneling)
|
||||
|
||||
@ -203,15 +349,15 @@ Teams tidak dapat menjangkau `localhost`. Gunakan tunnel untuk pengembangan loka
|
||||
|
||||
```bash
|
||||
ngrok http 3978
|
||||
# Salin URL https, mis. https://abc123.ngrok.io
|
||||
# Set messaging endpoint ke: https://abc123.ngrok.io/api/messages
|
||||
# Salin URL https, misalnya https://abc123.ngrok.io
|
||||
# Setel messaging endpoint ke: https://abc123.ngrok.io/api/messages
|
||||
```
|
||||
|
||||
**Opsi B: Tailscale Funnel**
|
||||
|
||||
```bash
|
||||
tailscale funnel 3978
|
||||
# Gunakan URL Tailscale funnel Anda sebagai messaging endpoint
|
||||
# Gunakan URL funnel Tailscale Anda sebagai messaging endpoint
|
||||
```
|
||||
|
||||
## Teams Developer Portal (Alternatif)
|
||||
@ -219,14 +365,14 @@ tailscale funnel 3978
|
||||
Alih-alih membuat ZIP manifest secara manual, Anda dapat menggunakan [Teams Developer Portal](https://dev.teams.microsoft.com/apps):
|
||||
|
||||
1. Klik **+ New app**
|
||||
2. Isi info dasar (nama, deskripsi, info developer)
|
||||
2. Isi info dasar (nama, deskripsi, info pengembang)
|
||||
3. Buka **App features** → **Bot**
|
||||
4. Pilih **Enter a bot ID manually** dan tempel Azure Bot App ID Anda
|
||||
5. Centang scope: **Personal**, **Team**, **Group Chat**
|
||||
5. Centang cakupan: **Personal**, **Team**, **Group Chat**
|
||||
6. Klik **Distribute** → **Download app package**
|
||||
7. Di Teams: **Apps** → **Manage your apps** → **Upload a custom app** → pilih ZIP
|
||||
|
||||
Ini sering lebih mudah daripada mengedit manifest JSON secara manual.
|
||||
Ini sering kali lebih mudah daripada mengedit manifest JSON secara manual.
|
||||
|
||||
## Menguji Bot
|
||||
|
||||
@ -234,9 +380,9 @@ Ini sering lebih mudah daripada mengedit manifest JSON secara manual.
|
||||
|
||||
1. Di Azure Portal → resource Azure Bot Anda → **Test in Web Chat**
|
||||
2. Kirim pesan - Anda seharusnya melihat respons
|
||||
3. Ini mengonfirmasi bahwa endpoint webhook Anda berfungsi sebelum penyiapan Teams
|
||||
3. Ini mengonfirmasi endpoint webhook Anda berfungsi sebelum penyiapan Teams
|
||||
|
||||
**Opsi B: Teams (setelah aplikasi diinstal)**
|
||||
**Opsi B: Teams (setelah instalasi aplikasi)**
|
||||
|
||||
1. Instal aplikasi Teams (sideload atau katalog organisasi)
|
||||
2. Temukan bot di Teams dan kirim DM
|
||||
@ -245,12 +391,12 @@ Ini sering lebih mudah daripada mengedit manifest JSON secara manual.
|
||||
## Penyiapan (minimal hanya teks)
|
||||
|
||||
1. **Pastikan plugin Microsoft Teams tersedia**
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya.
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya secara bawaan.
|
||||
- Instalasi lama/kustom dapat menambahkannya secara manual:
|
||||
- Dari npm: `openclaw plugins install @openclaw/msteams`
|
||||
- Dari checkout lokal: `openclaw plugins install ./path/to/local/msteams-plugin`
|
||||
|
||||
2. **Registrasi bot**
|
||||
2. **Pendaftaran bot**
|
||||
- Buat Azure Bot (lihat di atas) dan catat:
|
||||
- App ID
|
||||
- Client secret (App password)
|
||||
@ -258,11 +404,11 @@ Ini sering lebih mudah daripada mengedit manifest JSON secara manual.
|
||||
|
||||
3. **Manifest aplikasi Teams**
|
||||
- Sertakan entri `bot` dengan `botId = <App ID>`.
|
||||
- Scope: `personal`, `team`, `groupChat`.
|
||||
- `supportsFiles: true` (diperlukan untuk penanganan file dalam scope personal).
|
||||
- Cakupan: `personal`, `team`, `groupChat`.
|
||||
- `supportsFiles: true` (wajib untuk penanganan file pada cakupan personal).
|
||||
- Tambahkan izin RSC (di bawah).
|
||||
- Buat ikon: `outline.png` (32x32) dan `color.png` (192x192).
|
||||
- Zip ketiga file menjadi satu: `manifest.json`, `outline.png`, `color.png`.
|
||||
- Zip ketiga file bersama-sama: `manifest.json`, `outline.png`, `color.png`.
|
||||
|
||||
4. **Konfigurasikan OpenClaw**
|
||||
|
||||
@ -280,45 +426,50 @@ Ini sering lebih mudah daripada mengedit manifest JSON secara manual.
|
||||
}
|
||||
```
|
||||
|
||||
Anda juga dapat menggunakan variabel lingkungan alih-alih kunci config:
|
||||
Anda juga dapat menggunakan environment variable alih-alih kunci konfigurasi:
|
||||
- `MSTEAMS_APP_ID`
|
||||
- `MSTEAMS_APP_PASSWORD`
|
||||
- `MSTEAMS_TENANT_ID`
|
||||
- `MSTEAMS_AUTH_TYPE` (opsional: `"secret"` atau `"federated"`)
|
||||
- `MSTEAMS_CERTIFICATE_PATH` (federated + sertifikat)
|
||||
- `MSTEAMS_CERTIFICATE_THUMBPRINT` (opsional, tidak wajib untuk autentikasi)
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY` (federated + managed identity)
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (hanya untuk user-assigned MI)
|
||||
|
||||
5. **Endpoint bot**
|
||||
- Set Azure Bot Messaging Endpoint ke:
|
||||
- Setel Azure Bot Messaging Endpoint ke:
|
||||
- `https://<host>:3978/api/messages` (atau path/port pilihan Anda).
|
||||
|
||||
6. **Jalankan gateway**
|
||||
- Channel Teams dimulai secara otomatis saat plugin bawaan atau plugin yang diinstal manual tersedia dan config `msteams` ada beserta kredensialnya.
|
||||
- Saluran Teams dimulai secara otomatis saat plugin bawaan atau plugin yang diinstal manual tersedia dan konfigurasi `msteams` ada beserta kredensialnya.
|
||||
|
||||
## Aksi info anggota
|
||||
## Tindakan info anggota
|
||||
|
||||
OpenClaw mengekspos aksi `member-info` berbasis Graph untuk Microsoft Teams sehingga agen dan otomatisasi dapat me-resolve detail anggota channel (nama tampilan, email, peran) langsung dari Microsoft Graph.
|
||||
OpenClaw mengekspos tindakan `member-info` berbasis Graph untuk Microsoft Teams agar agen dan otomasi dapat menyelesaikan detail anggota saluran (nama tampilan, email, peran) langsung dari Microsoft Graph.
|
||||
|
||||
Persyaratan:
|
||||
|
||||
- Izin RSC `Member.Read.Group` (sudah ada dalam manifest yang direkomendasikan)
|
||||
- Untuk lookup lintas-team: izin Graph Application `User.Read.All` dengan admin consent
|
||||
- Untuk lookup lintas team: izin Aplikasi Graph `User.Read.All` dengan admin consent
|
||||
|
||||
Aksi ini di-gate oleh `channels.msteams.actions.memberInfo` (default: aktif saat kredensial Graph tersedia).
|
||||
Tindakan ini dikendalikan oleh `channels.msteams.actions.memberInfo` (default: aktif saat kredensial Graph tersedia).
|
||||
|
||||
## Konteks riwayat
|
||||
|
||||
- `channels.msteams.historyLimit` mengontrol berapa banyak pesan channel/grup terbaru yang dibungkus ke dalam prompt.
|
||||
- Fallback ke `messages.groupChat.historyLimit`. Set `0` untuk menonaktifkan (default 50).
|
||||
- Riwayat thread yang diambil difilter oleh allowlist pengirim (`allowFrom` / `groupAllowFrom`), sehingga penanaman konteks thread hanya menyertakan pesan dari pengirim yang diizinkan.
|
||||
- Konteks lampiran kutipan (`ReplyTo*` yang diturunkan dari HTML balasan Teams) saat ini diteruskan apa adanya.
|
||||
- Dengan kata lain, allowlist mengatur siapa yang dapat memicu agen; hanya jalur konteks tambahan tertentu yang difilter saat ini.
|
||||
- `channels.msteams.historyLimit` mengontrol berapa banyak pesan saluran/grup terbaru yang dibungkus ke dalam prompt.
|
||||
- Fallback ke `messages.groupChat.historyLimit`. Setel `0` untuk menonaktifkan (default 50).
|
||||
- Riwayat thread yang diambil difilter berdasarkan allowlist pengirim (`allowFrom` / `groupAllowFrom`), jadi penyemaian konteks thread hanya menyertakan pesan dari pengirim yang diizinkan.
|
||||
- Konteks lampiran kutipan (`ReplyTo*` yang diturunkan dari HTML balasan Teams) saat ini diteruskan sebagaimana diterima.
|
||||
- Dengan kata lain, allowlist mengendalikan siapa yang dapat memicu agen; saat ini hanya jalur konteks tambahan tertentu yang difilter.
|
||||
- Riwayat DM dapat dibatasi dengan `channels.msteams.dmHistoryLimit` (giliran pengguna). Override per pengguna: `channels.msteams.dms["<user_id>"].historyLimit`.
|
||||
|
||||
## Izin RSC Teams saat ini (Manifest)
|
||||
## Izin RSC Teams Saat Ini (Manifest)
|
||||
|
||||
Berikut adalah **resourceSpecific permissions** yang sudah ada di manifest aplikasi Teams kami. Izin ini hanya berlaku di dalam team/chat tempat aplikasi diinstal.
|
||||
Ini adalah **izin resourceSpecific yang ada** dalam manifest aplikasi Teams kami. Izin ini hanya berlaku di dalam team/chat tempat aplikasi diinstal.
|
||||
|
||||
**Untuk channel (scope team):**
|
||||
**Untuk saluran (cakupan team):**
|
||||
|
||||
- `ChannelMessage.Read.Group` (Application) - menerima semua teks pesan channel tanpa @mention
|
||||
- `ChannelMessage.Read.Group` (Application) - menerima semua pesan saluran tanpa @mention
|
||||
- `ChannelMessage.Send.Group` (Application)
|
||||
- `Member.Read.Group` (Application)
|
||||
- `Owner.Read.Group` (Application)
|
||||
@ -380,86 +531,86 @@ Contoh minimal yang valid dengan field yang diperlukan. Ganti ID dan URL.
|
||||
}
|
||||
```
|
||||
|
||||
### Catatan penting manifest (field wajib)
|
||||
### Catatan manifest (field yang wajib ada)
|
||||
|
||||
- `bots[].botId` **harus** cocok dengan Azure Bot App ID.
|
||||
- `webApplicationInfo.id` **harus** cocok dengan Azure Bot App ID.
|
||||
- `bots[].scopes` harus menyertakan surface yang ingin Anda gunakan (`personal`, `team`, `groupChat`).
|
||||
- `bots[].supportsFiles: true` diperlukan untuk penanganan file dalam scope personal.
|
||||
- `authorization.permissions.resourceSpecific` harus menyertakan izin baca/kirim channel jika Anda ingin traffic channel.
|
||||
- `bots[].scopes` harus menyertakan permukaan yang ingin Anda gunakan (`personal`, `team`, `groupChat`).
|
||||
- `bots[].supportsFiles: true` wajib untuk penanganan file pada cakupan personal.
|
||||
- `authorization.permissions.resourceSpecific` harus menyertakan pembacaan/pengiriman saluran jika Anda menginginkan lalu lintas saluran.
|
||||
|
||||
### Memperbarui aplikasi yang sudah ada
|
||||
|
||||
Untuk memperbarui aplikasi Teams yang sudah terinstal (misalnya untuk menambahkan izin RSC):
|
||||
Untuk memperbarui aplikasi Teams yang sudah terinstal (misalnya, untuk menambahkan izin RSC):
|
||||
|
||||
1. Perbarui `manifest.json` Anda dengan setelan baru
|
||||
2. **Naikkan field `version`** (mis. `1.0.0` → `1.1.0`)
|
||||
1. Perbarui `manifest.json` Anda dengan pengaturan baru
|
||||
2. **Naikkan field `version`** (misalnya `1.0.0` → `1.1.0`)
|
||||
3. **Zip ulang** manifest dengan ikon (`manifest.json`, `outline.png`, `color.png`)
|
||||
4. Unggah ZIP baru:
|
||||
4. Unggah zip baru:
|
||||
- **Opsi A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → temukan aplikasi Anda → Upload new version
|
||||
- **Opsi B (Sideload):** Di Teams → Apps → Manage your apps → Upload a custom app
|
||||
5. **Untuk channel team:** instal ulang aplikasi di setiap team agar izin baru berlaku
|
||||
6. **Keluar sepenuhnya lalu jalankan ulang Teams** (bukan hanya menutup jendela) untuk membersihkan metadata aplikasi yang di-cache
|
||||
5. **Untuk saluran team:** Instal ulang aplikasi di setiap team agar izin baru berlaku
|
||||
6. **Keluar sepenuhnya dan luncurkan ulang Teams** (bukan hanya menutup jendela) untuk menghapus metadata aplikasi yang tersimpan di cache
|
||||
|
||||
## Kapabilitas: hanya RSC vs Graph
|
||||
## Kemampuan: hanya RSC vs Graph
|
||||
|
||||
### Dengan **hanya Teams RSC** (aplikasi terinstal, tanpa izin Microsoft Graph API)
|
||||
### Dengan **Teams RSC saja** (aplikasi terinstal, tanpa izin API Graph)
|
||||
|
||||
Berfungsi:
|
||||
|
||||
- Membaca konten **teks** pesan channel.
|
||||
- Mengirim konten **teks** pesan channel.
|
||||
- Membaca konten **teks** pesan saluran.
|
||||
- Mengirim konten **teks** pesan saluran.
|
||||
- Menerima lampiran file **personal (DM)**.
|
||||
|
||||
Tidak berfungsi:
|
||||
TIDAK berfungsi:
|
||||
|
||||
- **Konten gambar atau file** channel/grup (payload hanya menyertakan stub HTML).
|
||||
- Konten **gambar atau file** saluran/grup (payload hanya menyertakan stub HTML).
|
||||
- Mengunduh lampiran yang disimpan di SharePoint/OneDrive.
|
||||
- Membaca riwayat pesan (di luar event webhook langsung).
|
||||
|
||||
### Dengan **Teams RSC + izin Microsoft Graph Application**
|
||||
### Dengan **Teams RSC + izin Aplikasi Microsoft Graph**
|
||||
|
||||
Menambahkan:
|
||||
|
||||
- Mengunduh hosted content (gambar yang ditempel ke pesan).
|
||||
- Mengunduh konten yang di-host (gambar yang ditempel ke dalam pesan).
|
||||
- Mengunduh lampiran file yang disimpan di SharePoint/OneDrive.
|
||||
- Membaca riwayat pesan channel/chat melalui Graph.
|
||||
- Membaca riwayat pesan saluran/chat melalui Graph.
|
||||
|
||||
### RSC vs Graph API
|
||||
|
||||
| Kapabilitas | Izin RSC | Graph API |
|
||||
| ----------------------- | --------------------- | ------------------------------------ |
|
||||
| **Pesan real-time** | Ya (melalui webhook) | Tidak (hanya polling) |
|
||||
| **Pesan historis** | Tidak | Ya (dapat mengambil riwayat) |
|
||||
| Capability | RSC Permissions | Graph API |
|
||||
| ----------------------- | --------------------- | --------------------------------------- |
|
||||
| **Pesan real-time** | Ya (melalui webhook) | Tidak (hanya polling) |
|
||||
| **Pesan historis** | Tidak | Ya (dapat mengkueri riwayat) |
|
||||
| **Kompleksitas setup** | Hanya manifest aplikasi | Memerlukan admin consent + alur token |
|
||||
| **Berfungsi offline** | Tidak (harus berjalan) | Ya (dapat melakukan query kapan saja) |
|
||||
| **Berfungsi offline** | Tidak (harus berjalan) | Ya (dapat mengkueri kapan saja) |
|
||||
|
||||
**Intinya:** RSC untuk mendengarkan secara real-time; Graph API untuk akses historis. Untuk mengejar pesan yang terlewat saat offline, Anda memerlukan Graph API dengan `ChannelMessage.Read.All` (memerlukan admin consent).
|
||||
**Intinya:** RSC adalah untuk mendengarkan secara real-time; Graph API adalah untuk akses historis. Untuk mengejar pesan yang terlewat saat offline, Anda memerlukan Graph API dengan `ChannelMessage.Read.All` (memerlukan admin consent).
|
||||
|
||||
## Media + riwayat dengan Graph (diperlukan untuk channel)
|
||||
## Media + riwayat dengan Graph (wajib untuk saluran)
|
||||
|
||||
Jika Anda memerlukan gambar/file di **channel** atau ingin mengambil **riwayat pesan**, Anda harus mengaktifkan izin Microsoft Graph dan memberikan admin consent.
|
||||
Jika Anda memerlukan gambar/file di **saluran** atau ingin mengambil **riwayat pesan**, Anda harus mengaktifkan izin Microsoft Graph dan memberikan admin consent.
|
||||
|
||||
1. Di Entra ID (Azure AD) **App Registration**, tambahkan Microsoft Graph **Application permissions**:
|
||||
- `ChannelMessage.Read.All` (lampiran channel + riwayat)
|
||||
1. Di **App Registration** Entra ID (Azure AD), tambahkan izin **Aplikasi** Microsoft Graph:
|
||||
- `ChannelMessage.Read.All` (lampiran saluran + riwayat)
|
||||
- `Chat.Read.All` atau `ChatMessage.Read.All` (obrolan grup)
|
||||
2. **Berikan admin consent** untuk tenant.
|
||||
3. Naikkan **versi manifest** aplikasi Teams, unggah ulang, dan **instal ulang aplikasi di Teams**.
|
||||
4. **Keluar sepenuhnya lalu jalankan ulang Teams** untuk membersihkan metadata aplikasi yang di-cache.
|
||||
4. **Keluar sepenuhnya dan luncurkan ulang Teams** untuk menghapus metadata aplikasi yang tersimpan di cache.
|
||||
|
||||
**Izin tambahan untuk mention pengguna:** Mention @pengguna berfungsi langsung untuk pengguna dalam percakapan. Namun, jika Anda ingin mencari dan me-mention pengguna secara dinamis yang **tidak berada dalam percakapan saat ini**, tambahkan izin `User.Read.All` (Application) dan berikan admin consent.
|
||||
**Izin tambahan untuk mention pengguna:** @mention pengguna berfungsi langsung untuk pengguna yang ada dalam percakapan. Namun, jika Anda ingin mencari dan menyebut pengguna secara dinamis yang **tidak ada dalam percakapan saat ini**, tambahkan izin `User.Read.All` (Application) dan berikan admin consent.
|
||||
|
||||
## Keterbatasan yang diketahui
|
||||
## Keterbatasan yang Diketahui
|
||||
|
||||
### Timeout webhook
|
||||
|
||||
Teams mengirim pesan melalui webhook HTTP. Jika pemrosesan terlalu lama (misalnya respons LLM lambat), Anda mungkin melihat:
|
||||
Teams mengirimkan pesan melalui webhook HTTP. Jika pemrosesan memakan waktu terlalu lama (misalnya, respons LLM lambat), Anda mungkin melihat:
|
||||
|
||||
- Timeout gateway
|
||||
- Teams mencoba ulang pesan (menyebabkan duplikasi)
|
||||
- Balasan yang terlewat
|
||||
|
||||
OpenClaw menanganinya dengan mengembalikan respons dengan cepat dan mengirim balasan secara proaktif, tetapi respons yang sangat lambat masih dapat menyebabkan masalah.
|
||||
OpenClaw menangani ini dengan mengembalikan respons cepat dan mengirim balasan secara proaktif, tetapi respons yang sangat lambat tetap dapat menimbulkan masalah.
|
||||
|
||||
### Pemformatan
|
||||
|
||||
@ -467,61 +618,66 @@ Markdown Teams lebih terbatas daripada Slack atau Discord:
|
||||
|
||||
- Pemformatan dasar berfungsi: **tebal**, _miring_, `code`, tautan
|
||||
- Markdown kompleks (tabel, daftar bertingkat) mungkin tidak dirender dengan benar
|
||||
- Adaptive Cards didukung untuk poll dan pengiriman card arbitrer (lihat di bawah)
|
||||
- Adaptive Cards didukung untuk polls dan pengiriman kartu arbitrer (lihat di bawah)
|
||||
|
||||
## Konfigurasi
|
||||
|
||||
Setelan utama (lihat `/gateway/configuration` untuk pola channel bersama):
|
||||
Pengaturan utama (lihat `/gateway/configuration` untuk pola saluran bersama):
|
||||
|
||||
- `channels.msteams.enabled`: aktifkan/nonaktifkan channel.
|
||||
- `channels.msteams.enabled`: aktifkan/nonaktifkan saluran.
|
||||
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: kredensial bot.
|
||||
- `channels.msteams.webhook.port` (default `3978`)
|
||||
- `channels.msteams.webhook.path` (default `/api/messages`)
|
||||
- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing)
|
||||
- `channels.msteams.allowFrom`: allowlist DM (AAD object ID direkomendasikan). Wizard me-resolve nama ke ID selama setup saat akses Graph tersedia.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching`: toggle break-glass untuk mengaktifkan kembali pencocokan UPN/nama tampilan yang bisa berubah dan perutean langsung nama team/channel.
|
||||
- `channels.msteams.textChunkLimit`: ukuran chunk teks outbound.
|
||||
- `channels.msteams.chunkMode`: `length` (default) atau `newline` untuk memisah berdasarkan baris kosong (batas paragraf) sebelum chunking berdasarkan panjang.
|
||||
- `channels.msteams.allowFrom`: allowlist DM (ID objek AAD direkomendasikan). Wizard menyelesaikan nama menjadi ID selama penyiapan saat akses Graph tersedia.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching`: toggle break-glass untuk mengaktifkan kembali pencocokan UPN/nama tampilan yang dapat berubah dan perutean langsung nama team/saluran.
|
||||
- `channels.msteams.textChunkLimit`: ukuran chunk teks keluar.
|
||||
- `channels.msteams.chunkMode`: `length` (default) atau `newline` untuk memisah pada baris kosong (batas paragraf) sebelum chunking berdasarkan panjang.
|
||||
- `channels.msteams.mediaAllowHosts`: allowlist untuk host lampiran masuk (default ke domain Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts`: allowlist untuk melampirkan header Authorization pada percobaan ulang media (default ke host Graph + Bot Framework).
|
||||
- `channels.msteams.requireMention`: wajibkan @mention di channel/grup (default true).
|
||||
- `channels.msteams.requireMention`: mewajibkan @mention di saluran/grup (default true).
|
||||
- `channels.msteams.replyStyle`: `thread | top-level` (lihat [Gaya Balasan](#reply-style-threads-vs-posts)).
|
||||
- `channels.msteams.teams.<teamId>.replyStyle`: override per-team.
|
||||
- `channels.msteams.teams.<teamId>.requireMention`: override per-team.
|
||||
- `channels.msteams.teams.<teamId>.tools`: override kebijakan tool default per-team (`allow`/`deny`/`alsoAllow`) yang digunakan saat override channel tidak ada.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender`: override kebijakan tool per-pengirim default per-team (`"*"` wildcard didukung).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: override per-channel.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: override per-channel.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: override kebijakan tool per-channel (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: override kebijakan tool per-pengirim per-channel (`"*"` wildcard didukung).
|
||||
- Kunci `toolsBySender` sebaiknya menggunakan prefiks eksplisit:
|
||||
`id:`, `e164:`, `username:`, `name:` (kunci lama tanpa prefiks masih dipetakan hanya ke `id:`).
|
||||
- `channels.msteams.actions.memberInfo`: aktifkan atau nonaktifkan aksi info anggota berbasis Graph (default: aktif saat kredensial Graph tersedia).
|
||||
- `channels.msteams.sharePointSiteId`: SharePoint site ID untuk upload file di obrolan grup/channel (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)).
|
||||
- `channels.msteams.teams.<teamId>.tools`: override kebijakan tool default per-team (`allow`/`deny`/`alsoAllow`) yang digunakan saat override saluran tidak ada.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender`: override kebijakan tool default per-team per-pengirim (`"*"` wildcard didukung).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: override per-saluran.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: override per-saluran.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: override kebijakan tool per-saluran (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: override kebijakan tool per-saluran per-pengirim (`"*"` wildcard didukung).
|
||||
- Kunci `toolsBySender` harus menggunakan prefiks eksplisit:
|
||||
`id:`, `e164:`, `username:`, `name:` (kunci lama tanpa prefiks masih dipetakan ke `id:` saja).
|
||||
- `channels.msteams.actions.memberInfo`: aktifkan atau nonaktifkan tindakan info anggota berbasis Graph (default: aktif saat kredensial Graph tersedia).
|
||||
- `channels.msteams.authType`: jenis autentikasi — `"secret"` (default) atau `"federated"`.
|
||||
- `channels.msteams.certificatePath`: path ke file sertifikat PEM (federated + autentikasi sertifikat).
|
||||
- `channels.msteams.certificateThumbprint`: thumbprint sertifikat (opsional, tidak wajib untuk autentikasi).
|
||||
- `channels.msteams.useManagedIdentity`: aktifkan autentikasi managed identity (mode federated).
|
||||
- `channels.msteams.managedIdentityClientId`: client ID untuk managed identity user-assigned.
|
||||
- `channels.msteams.sharePointSiteId`: ID situs SharePoint untuk unggahan file di obrolan grup/saluran (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)).
|
||||
|
||||
## Perutean & Sesi
|
||||
|
||||
- Kunci sesi mengikuti format agen standar (lihat [/concepts/session](/concepts/session)):
|
||||
- Direct message berbagi sesi utama (`agent:<agentId>:<mainKey>`).
|
||||
- Pesan channel/grup menggunakan ID percakapan:
|
||||
- Kunci sesi mengikuti format agen standar (lihat [/concepts/session](/id/concepts/session)):
|
||||
- Pesan langsung berbagi sesi utama (`agent:<agentId>:<mainKey>`).
|
||||
- Pesan saluran/grup menggunakan ID percakapan:
|
||||
- `agent:<agentId>:msteams:channel:<conversationId>`
|
||||
- `agent:<agentId>:msteams:group:<conversationId>`
|
||||
|
||||
## Gaya Balasan: Threads vs Posts
|
||||
## Gaya Balasan: Thread vs Postingan
|
||||
|
||||
Teams baru-baru ini memperkenalkan dua gaya UI channel di atas model data dasar yang sama:
|
||||
Teams baru-baru ini memperkenalkan dua gaya UI saluran di atas model data dasar yang sama:
|
||||
|
||||
| Gaya | Deskripsi | `replyStyle` yang direkomendasikan |
|
||||
| ----------------------- | ------------------------------------------------------ | ---------------------------------- |
|
||||
| **Posts** (klasik) | Pesan muncul sebagai kartu dengan balasan ber-thread di bawahnya | `thread` (default) |
|
||||
| **Threads** (mirip Slack) | Pesan mengalir secara linear, lebih mirip Slack | `top-level` |
|
||||
| Style | Description | `replyStyle` yang direkomendasikan |
|
||||
| ------------------------ | ------------------------------------------------------------ | ---------------------------------- |
|
||||
| **Posts** (klasik) | Pesan muncul sebagai kartu dengan balasan berutas di bawahnya | `thread` (default) |
|
||||
| **Threads** (mirip Slack) | Pesan mengalir secara linear, lebih mirip Slack | `top-level` |
|
||||
|
||||
**Masalahnya:** API Teams tidak mengekspos gaya UI channel yang digunakan. Jika Anda menggunakan `replyStyle` yang salah:
|
||||
**Masalahnya:** API Teams tidak mengekspos gaya UI yang digunakan saluran. Jika Anda menggunakan `replyStyle` yang salah:
|
||||
|
||||
- `thread` di channel bergaya Threads → balasan muncul bertingkat secara janggal
|
||||
- `top-level` di channel bergaya Posts → balasan muncul sebagai post top-level terpisah, bukan di dalam thread
|
||||
- `thread` di saluran bergaya Threads → balasan tampak bertingkat dengan canggung
|
||||
- `top-level` di saluran bergaya Posts → balasan muncul sebagai postingan tingkat atas terpisah, bukan di dalam thread
|
||||
|
||||
**Solusi:** Konfigurasikan `replyStyle` per-channel berdasarkan cara channel disiapkan:
|
||||
**Solusi:** Konfigurasikan `replyStyle` per-saluran berdasarkan cara saluran disiapkan:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -547,28 +703,28 @@ Teams baru-baru ini memperkenalkan dua gaya UI channel di atas model data dasar
|
||||
**Keterbatasan saat ini:**
|
||||
|
||||
- **DM:** Gambar dan lampiran file berfungsi melalui API file bot Teams.
|
||||
- **Channel/grup:** Lampiran berada di penyimpanan M365 (SharePoint/OneDrive). Payload webhook hanya menyertakan stub HTML, bukan byte file yang sebenarnya. **Izin Graph API diperlukan** untuk mengunduh lampiran channel.
|
||||
- Untuk pengiriman eksplisit yang mengutamakan file, gunakan `action=upload-file` dengan `media` / `filePath` / `path`; `message` opsional menjadi teks/komentar pendamping, dan `filename` menimpa nama yang diunggah.
|
||||
- **Saluran/grup:** Lampiran berada di penyimpanan M365 (SharePoint/OneDrive). Payload webhook hanya menyertakan stub HTML, bukan byte file sebenarnya. **Izin Graph API diperlukan** untuk mengunduh lampiran saluran.
|
||||
- Untuk pengiriman eksplisit yang mengutamakan file, gunakan `action=upload-file` dengan `media` / `filePath` / `path`; `message` opsional menjadi teks/komentar pendamping, dan `filename` menggantikan nama yang diunggah.
|
||||
|
||||
Tanpa izin Graph, pesan channel dengan gambar akan diterima sebagai teks saja (konten gambar tidak dapat diakses bot).
|
||||
Secara default, OpenClaw hanya mengunduh media dari hostname Microsoft/Teams. Timpa dengan `channels.msteams.mediaAllowHosts` (gunakan `["*"]` untuk mengizinkan host mana pun).
|
||||
Header Authorization hanya dilampirkan untuk host dalam `channels.msteams.mediaAuthAllowHosts` (default ke host Graph + Bot Framework). Jaga daftar ini tetap ketat (hindari suffix multi-tenant).
|
||||
Tanpa izin Graph, pesan saluran dengan gambar akan diterima sebagai teks saja (konten gambar tidak dapat diakses oleh bot).
|
||||
Secara default, OpenClaw hanya mengunduh media dari hostname Microsoft/Teams. Override dengan `channels.msteams.mediaAllowHosts` (gunakan `["*"]` untuk mengizinkan host apa pun).
|
||||
Header Authorization hanya dilampirkan untuk host di `channels.msteams.mediaAuthAllowHosts` (default ke host Graph + Bot Framework). Pertahankan daftar ini tetap ketat (hindari suffix multi-tenant).
|
||||
|
||||
## Mengirim file di obrolan grup
|
||||
|
||||
Bot dapat mengirim file di DM menggunakan alur FileConsentCard (bawaan). Namun, **mengirim file di obrolan grup/channel** memerlukan setup tambahan:
|
||||
Bot dapat mengirim file di DM menggunakan alur FileConsentCard (bawaan). Namun, **mengirim file di obrolan grup/saluran** memerlukan penyiapan tambahan:
|
||||
|
||||
| Konteks | Cara file dikirim | Setup yang diperlukan |
|
||||
| ------------------------ | -------------------------------------------- | -------------------------------------------------- |
|
||||
| **DM** | FileConsentCard → pengguna menerima → bot mengunggah | Langsung berfungsi |
|
||||
| **Obrolan grup/channel** | Unggah ke SharePoint → bagikan tautan | Memerlukan `sharePointSiteId` + izin Graph |
|
||||
| **Gambar (konteks apa pun)** | Inline berkode Base64 | Langsung berfungsi |
|
||||
| Context | How files are sent | Setup needed |
|
||||
| ------------------------ | ------------------------------------------ | ----------------------------------------------- |
|
||||
| **DM** | FileConsentCard → pengguna menerima → bot mengunggah | Langsung berfungsi |
|
||||
| **Obrolan grup/saluran** | Unggah ke SharePoint → bagikan tautan | Memerlukan `sharePointSiteId` + izin Graph |
|
||||
| **Gambar (konteks apa pun)** | Inline dengan enkode Base64 | Langsung berfungsi |
|
||||
|
||||
### Mengapa obrolan grup memerlukan SharePoint
|
||||
|
||||
Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak berfungsi untuk identitas aplikasi). Untuk mengirim file di obrolan grup/channel, bot mengunggah ke **situs SharePoint** dan membuat tautan berbagi.
|
||||
Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak berfungsi untuk identitas aplikasi). Untuk mengirim file di obrolan grup/saluran, bot mengunggah ke **situs SharePoint** dan membuat tautan berbagi.
|
||||
|
||||
### Setup
|
||||
### Penyiapan
|
||||
|
||||
1. **Tambahkan izin Graph API** di Entra ID (Azure AD) → App Registration:
|
||||
- `Sites.ReadWrite.All` (Application) - unggah file ke SharePoint
|
||||
@ -579,7 +735,7 @@ Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak
|
||||
3. **Dapatkan ID situs SharePoint Anda:**
|
||||
|
||||
```bash
|
||||
# Via Graph Explorer atau curl dengan token yang valid:
|
||||
# Melalui Graph Explorer atau curl dengan token yang valid:
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
|
||||
|
||||
@ -596,7 +752,7 @@ Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
// ... config lain ...
|
||||
// ... konfigurasi lain ...
|
||||
sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
|
||||
},
|
||||
},
|
||||
@ -605,40 +761,40 @@ Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak
|
||||
|
||||
### Perilaku berbagi
|
||||
|
||||
| Izin | Perilaku berbagi |
|
||||
| --------------------------------------- | --------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` saja | Tautan berbagi ke seluruh organisasi (siapa pun di org dapat mengakses) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Tautan berbagi per-pengguna (hanya anggota chat yang dapat mengakses) |
|
||||
| Permission | Sharing behavior |
|
||||
| --------------------------------------- | ------------------------------------------------------------ |
|
||||
| `Sites.ReadWrite.All` saja | Tautan berbagi ke seluruh organisasi (siapa pun di organisasi dapat mengakses) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Tautan berbagi per-pengguna (hanya anggota chat yang dapat mengakses) |
|
||||
|
||||
Berbagi per-pengguna lebih aman karena hanya peserta chat yang dapat mengakses file. Jika izin `Chat.Read.All` tidak ada, bot fallback ke berbagi seluruh organisasi.
|
||||
Berbagi per-pengguna lebih aman karena hanya peserta chat yang dapat mengakses file. Jika izin `Chat.Read.All` tidak ada, bot akan fallback ke berbagi ke seluruh organisasi.
|
||||
|
||||
### Perilaku fallback
|
||||
|
||||
| Skenario | Hasil |
|
||||
| ------------------------------------------------- | -------------------------------------------------- |
|
||||
| Obrolan grup + file + `sharePointSiteId` dikonfigurasi | Unggah ke SharePoint, kirim tautan berbagi |
|
||||
| Obrolan grup + file + tanpa `sharePointSiteId` | Coba unggah ke OneDrive (mungkin gagal), kirim teks saja |
|
||||
| Obrolan personal + file | Alur FileConsentCard (berfungsi tanpa SharePoint) |
|
||||
| Konteks apa pun + gambar | Inline berkode Base64 (berfungsi tanpa SharePoint) |
|
||||
| Scenario | Result |
|
||||
| ------------------------------------------------- | ---------------------------------------------------- |
|
||||
| Obrolan grup + file + `sharePointSiteId` dikonfigurasi | Unggah ke SharePoint, kirim tautan berbagi |
|
||||
| Obrolan grup + file + tidak ada `sharePointSiteId` | Coba unggah ke OneDrive (mungkin gagal), kirim teks saja |
|
||||
| Chat personal + file | Alur FileConsentCard (berfungsi tanpa SharePoint) |
|
||||
| Konteks apa pun + gambar | Inline dengan enkode Base64 (berfungsi tanpa SharePoint) |
|
||||
|
||||
### Lokasi penyimpanan file
|
||||
|
||||
File yang diunggah disimpan di folder `/OpenClawShared/` di pustaka dokumen default situs SharePoint yang dikonfigurasi.
|
||||
File yang diunggah disimpan di folder `/OpenClawShared/` dalam pustaka dokumen default situs SharePoint yang dikonfigurasi.
|
||||
|
||||
## Poll (Adaptive Cards)
|
||||
## Polls (Adaptive Cards)
|
||||
|
||||
OpenClaw mengirim poll Teams sebagai Adaptive Cards (tidak ada API poll Teams bawaan).
|
||||
OpenClaw mengirim polls Teams sebagai Adaptive Cards (tidak ada API poll Teams native).
|
||||
|
||||
- CLI: `openclaw message poll --channel msteams --target conversation:<id> ...`
|
||||
- Suara dicatat oleh gateway di `~/.openclaw/msteams-polls.json`.
|
||||
- Gateway harus tetap online untuk mencatat suara.
|
||||
- Poll belum otomatis mem-posting ringkasan hasil (periksa file penyimpanan jika perlu).
|
||||
- Vote dicatat oleh gateway di `~/.openclaw/msteams-polls.json`.
|
||||
- Gateway harus tetap online untuk mencatat vote.
|
||||
- Poll belum otomatis memposting ringkasan hasil (periksa file store jika diperlukan).
|
||||
|
||||
## Adaptive Cards (arbitrer)
|
||||
|
||||
Kirim JSON Adaptive Card apa pun ke pengguna atau percakapan Teams menggunakan tool `message` atau CLI.
|
||||
|
||||
Parameter `card` menerima objek JSON Adaptive Card. Saat `card` disediakan, teks pesan bersifat opsional.
|
||||
Parameter `card` menerima objek JSON Adaptive Card. Saat `card` diberikan, teks pesan bersifat opsional.
|
||||
|
||||
**Tool agen:**
|
||||
|
||||
@ -663,18 +819,18 @@ openclaw message send --channel msteams \
|
||||
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
|
||||
```
|
||||
|
||||
Lihat [dokumentasi Adaptive Cards](https://adaptivecards.io/) untuk skema card dan contoh. Untuk detail format target, lihat [Format target](#target-formats) di bawah.
|
||||
Lihat [dokumentasi Adaptive Cards](https://adaptivecards.io/) untuk skema kartu dan contoh. Untuk detail format target, lihat [Format target](#target-formats) di bawah.
|
||||
|
||||
## Format target
|
||||
|
||||
Target MSTeams menggunakan prefiks untuk membedakan pengguna dan percakapan:
|
||||
|
||||
| Jenis target | Format | Contoh |
|
||||
| -------------------- | -------------------------------- | --------------------------------------------------- |
|
||||
| Pengguna (berdasarkan ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Pengguna (berdasarkan nama) | `user:<display-name>` | `user:John Smith` (memerlukan Graph API) |
|
||||
| Grup/channel | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Grup/channel (mentah) | `<conversation-id>` | `19:abc123...@thread.tacv2` (jika mengandung `@thread`) |
|
||||
| Target type | Format | Example |
|
||||
| ------------------- | -------------------------------- | --------------------------------------------------- |
|
||||
| Pengguna (berdasarkan ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Pengguna (berdasarkan nama) | `user:<display-name>` | `user:John Smith` (memerlukan Graph API) |
|
||||
| Grup/saluran | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Grup/saluran (raw) | `<conversation-id>` | `19:abc123...@thread.tacv2` (jika mengandung `@thread`) |
|
||||
|
||||
**Contoh CLI:**
|
||||
|
||||
@ -685,7 +841,7 @@ openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "
|
||||
# Kirim ke pengguna berdasarkan nama tampilan (memicu lookup Graph API)
|
||||
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
|
||||
|
||||
# Kirim ke obrolan grup atau channel
|
||||
# Kirim ke obrolan grup atau saluran
|
||||
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"
|
||||
|
||||
# Kirim Adaptive Card ke percakapan
|
||||
@ -717,71 +873,71 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread.
|
||||
}
|
||||
```
|
||||
|
||||
Catatan: Tanpa prefiks `user:`, nama secara default di-resolve sebagai grup/team. Selalu gunakan `user:` saat menargetkan orang berdasarkan nama tampilan.
|
||||
Catatan: Tanpa prefiks `user:`, nama secara default akan menggunakan resolusi grup/team. Selalu gunakan `user:` saat menargetkan orang berdasarkan nama tampilan.
|
||||
|
||||
## Pesan proaktif
|
||||
|
||||
- Pesan proaktif hanya dimungkinkan **setelah** pengguna berinteraksi, karena saat itulah kami menyimpan referensi percakapan.
|
||||
- Lihat `/gateway/configuration` untuk gating `dmPolicy` dan allowlist.
|
||||
- Pesan proaktif hanya dimungkinkan **setelah** pengguna berinteraksi, karena kami menyimpan referensi percakapan pada saat itu.
|
||||
- Lihat `/gateway/configuration` untuk gerbang `dmPolicy` dan allowlist.
|
||||
|
||||
## ID Team dan Channel (Jebakan Umum)
|
||||
## ID Team dan Saluran (Kesalahan Umum)
|
||||
|
||||
Parameter kueri `groupId` di URL Teams **BUKAN** team ID yang digunakan untuk konfigurasi. Ekstrak ID dari path URL sebagai gantinya:
|
||||
Parameter kueri `groupId` dalam URL Teams **BUKAN** ID team yang digunakan untuk konfigurasi. Ekstrak ID dari path URL sebagai gantinya:
|
||||
|
||||
**URL Team:**
|
||||
|
||||
```
|
||||
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
|
||||
└────────────────────────────┘
|
||||
Team ID (URL-decode ini)
|
||||
ID Team (lakukan URL-decode untuk ini)
|
||||
```
|
||||
|
||||
**URL Channel:**
|
||||
**URL Saluran:**
|
||||
|
||||
```
|
||||
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
|
||||
└─────────────────────────┘
|
||||
Channel ID (URL-decode ini)
|
||||
ID Saluran (lakukan URL-decode untuk ini)
|
||||
```
|
||||
|
||||
**Untuk config:**
|
||||
**Untuk konfigurasi:**
|
||||
|
||||
- Team ID = segmen path setelah `/team/` (URL-decoded, mis. `19:Bk4j...@thread.tacv2`)
|
||||
- Channel ID = segmen path setelah `/channel/` (URL-decoded)
|
||||
- ID Team = segmen path setelah `/team/` (hasil URL-decode, misalnya `19:Bk4j...@thread.tacv2`)
|
||||
- ID Saluran = segmen path setelah `/channel/` (hasil URL-decode)
|
||||
- **Abaikan** parameter kueri `groupId`
|
||||
|
||||
## Channel Privat
|
||||
## Saluran Privat
|
||||
|
||||
Bot memiliki dukungan terbatas di channel privat:
|
||||
Bot memiliki dukungan terbatas di saluran privat:
|
||||
|
||||
| Fitur | Channel Standar | Channel Privat |
|
||||
| ---------------------------- | --------------- | --------------------- |
|
||||
| Instalasi bot | Ya | Terbatas |
|
||||
| Pesan real-time (webhook) | Ya | Mungkin tidak berfungsi |
|
||||
| Izin RSC | Ya | Dapat berperilaku berbeda |
|
||||
| @mentions | Ya | Jika bot dapat diakses |
|
||||
| Riwayat Graph API | Ya | Ya (dengan izin) |
|
||||
| Feature | Standard Channels | Private Channels |
|
||||
| ---------------------------- | ----------------- | --------------------- |
|
||||
| Instalasi bot | Ya | Terbatas |
|
||||
| Pesan real-time (webhook) | Ya | Mungkin tidak berfungsi |
|
||||
| Izin RSC | Ya | Mungkin berperilaku berbeda |
|
||||
| @mentions | Ya | Jika bot dapat diakses |
|
||||
| Riwayat Graph API | Ya | Ya (dengan izin) |
|
||||
|
||||
**Solusi sementara jika channel privat tidak berfungsi:**
|
||||
**Solusi jika saluran privat tidak berfungsi:**
|
||||
|
||||
1. Gunakan channel standar untuk interaksi bot
|
||||
1. Gunakan saluran standar untuk interaksi bot
|
||||
2. Gunakan DM - pengguna selalu dapat mengirim pesan langsung ke bot
|
||||
3. Gunakan Graph API untuk akses historis (memerlukan `ChannelMessage.Read.All`)
|
||||
|
||||
## Pemecahan masalah
|
||||
## Pemecahan Masalah
|
||||
|
||||
### Masalah umum
|
||||
|
||||
- **Gambar tidak muncul di channel:** izin Graph atau admin consent belum ada. Instal ulang aplikasi Teams dan keluar/buka kembali Teams sepenuhnya.
|
||||
- **Tidak ada respons di channel:** mention diwajibkan secara default; set `channels.msteams.requireMention=false` atau konfigurasikan per team/channel.
|
||||
- **Ketidakcocokan versi (Teams masih menampilkan manifest lama):** hapus + tambahkan kembali aplikasi dan keluar sepenuhnya dari Teams untuk refresh.
|
||||
- **401 Unauthorized dari webhook:** Wajar saat menguji manual tanpa Azure JWT - artinya endpoint dapat dijangkau tetapi autentikasi gagal. Gunakan Azure Web Chat untuk menguji dengan benar.
|
||||
- **Gambar tidak muncul di saluran:** izin Graph atau admin consent belum ada. Instal ulang aplikasi Teams dan keluar/buka kembali Teams sepenuhnya.
|
||||
- **Tidak ada respons di saluran:** mention diwajibkan secara default; setel `channels.msteams.requireMention=false` atau konfigurasikan per team/saluran.
|
||||
- **Versi tidak cocok (Teams masih menampilkan manifest lama):** hapus + tambahkan ulang aplikasi dan keluar dari Teams sepenuhnya untuk menyegarkan.
|
||||
- **401 Unauthorized dari webhook:** Ini wajar saat menguji secara manual tanpa Azure JWT - artinya endpoint dapat dijangkau tetapi autentikasi gagal. Gunakan Azure Web Chat untuk pengujian yang benar.
|
||||
|
||||
### Error upload manifest
|
||||
### Kesalahan unggah manifest
|
||||
|
||||
- **"Icon file cannot be empty":** Manifest merujuk file ikon yang berukuran 0 byte. Buat ikon PNG yang valid (32x32 untuk `outline.png`, 192x192 untuk `color.png`).
|
||||
- **"webApplicationInfo.Id already in use":** Aplikasi masih terinstal di team/chat lain. Temukan dan uninstall terlebih dahulu, atau tunggu 5-10 menit untuk propagasi.
|
||||
- **"Something went wrong" saat upload:** Unggah melalui [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), lalu buka browser DevTools (F12) → tab Network, dan periksa body respons untuk error sebenarnya.
|
||||
- **"Icon file cannot be empty":** Manifest mereferensikan file ikon yang berukuran 0 byte. Buat ikon PNG yang valid (32x32 untuk `outline.png`, 192x192 untuk `color.png`).
|
||||
- **"webApplicationInfo.Id already in use":** Aplikasi masih terinstal di team/chat lain. Temukan dan copot pemasangannya terlebih dahulu, atau tunggu 5-10 menit untuk propagasi.
|
||||
- **"Something went wrong" saat unggah:** Unggah melalui [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) sebagai gantinya, buka browser DevTools (F12) → tab Network, dan periksa body respons untuk melihat kesalahan sebenarnya.
|
||||
- **Sideload gagal:** Coba "Upload an app to your org's app catalog" alih-alih "Upload a custom app" - ini sering melewati pembatasan sideload.
|
||||
|
||||
### Izin RSC tidak berfungsi
|
||||
@ -789,22 +945,22 @@ Bot memiliki dukungan terbatas di channel privat:
|
||||
1. Verifikasi `webApplicationInfo.id` cocok persis dengan App ID bot Anda
|
||||
2. Unggah ulang aplikasi dan instal ulang di team/chat
|
||||
3. Periksa apakah admin organisasi Anda memblokir izin RSC
|
||||
4. Pastikan Anda menggunakan scope yang benar: `ChannelMessage.Read.Group` untuk teams, `ChatMessage.Read.Chat` untuk obrolan grup
|
||||
4. Konfirmasikan Anda menggunakan cakupan yang benar: `ChannelMessage.Read.Group` untuk teams, `ChatMessage.Read.Chat` untuk obrolan grup
|
||||
|
||||
## Referensi
|
||||
|
||||
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - panduan setup Azure Bot
|
||||
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - panduan penyiapan Azure Bot
|
||||
- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - membuat/mengelola aplikasi Teams
|
||||
- [Skema manifest aplikasi Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
|
||||
- [Menerima pesan channel dengan RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
|
||||
- [Referensi izin RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
|
||||
- [Penanganan file bot Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (channel/grup memerlukan Graph)
|
||||
- [Pesan proaktif](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) (saluran/grup memerlukan Graph)
|
||||
- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Ringkasan Channel](/channels) — semua channel yang didukung
|
||||
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Groups](/channels/groups) — perilaku obrolan grup dan gating mention
|
||||
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/gateway/security) — model akses dan hardening
|
||||
- [Ikhtisar Saluran](/id/channels) — semua saluran yang didukung
|
||||
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Grup](/id/channels/groups) — perilaku obrolan grup dan gerbang mention
|
||||
- [Perutean Saluran](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan hardening
|
||||
|
||||
@ -1,60 +1,60 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda sedang mengubah runtime agen tertanam atau registri harness
|
||||
- Anda sedang mendaftarkan harness agen dari plugin terbundel atau tepercaya
|
||||
- Anda perlu memahami bagaimana plugin Codex berhubungan dengan provider model
|
||||
- Anda sedang mengubah runtime agen tertanam atau registry harness
|
||||
- Anda sedang mendaftarkan harness agen dari plugin bawaan atau tepercaya
|
||||
- Anda perlu memahami bagaimana plugin Codex berhubungan dengan penyedia model
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Permukaan SDK eksperimental untuk plugin yang menggantikan eksekutor agen tertanam tingkat rendah
|
||||
title: Plugin Harness Agen
|
||||
title: Plugin Agent Harness
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:09Z"
|
||||
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
|
||||
---
|
||||
|
||||
# Plugin Harness Agen
|
||||
# Plugin Agent Harness
|
||||
|
||||
**Harness agen** adalah eksekutor tingkat rendah untuk satu giliran agen OpenClaw
|
||||
yang sudah disiapkan. Ini bukan provider model, bukan saluran, dan bukan registri alat.
|
||||
**Agent harness** adalah eksekutor tingkat rendah untuk satu giliran agen OpenClaw
|
||||
yang sudah disiapkan. Ini bukan penyedia model, bukan channel, dan bukan registry tool.
|
||||
|
||||
Gunakan permukaan ini hanya untuk plugin native yang terbundel atau tepercaya. Kontrak ini
|
||||
Gunakan permukaan ini hanya untuk plugin native bawaan atau tepercaya. Kontrak ini
|
||||
masih eksperimental karena tipe parameternya sengaja mencerminkan runner
|
||||
tertanam saat ini.
|
||||
|
||||
## Kapan menggunakan harness
|
||||
|
||||
Daftarkan harness agen ketika sebuah keluarga model memiliki runtime sesi native
|
||||
sendiri dan transport provider OpenClaw normal bukan abstraksi yang tepat.
|
||||
Daftarkan agent harness saat sebuah keluarga model memiliki runtime sesi native
|
||||
sendiri dan transport penyedia OpenClaw normal adalah abstraksi yang salah.
|
||||
|
||||
Contoh:
|
||||
|
||||
- server agen coding native yang memiliki thread dan compaction sendiri
|
||||
- server agen pengodean native yang memiliki thread dan compaction
|
||||
- CLI atau daemon lokal yang harus melakukan streaming event plan/reasoning/tool native
|
||||
- runtime model yang membutuhkan resume id sendiri selain transkrip sesi
|
||||
OpenClaw
|
||||
- runtime model yang memerlukan resume id sendiri selain transkrip sesi OpenClaw
|
||||
|
||||
Jangan mendaftarkan harness hanya untuk menambahkan API LLM baru. Untuk API model HTTP atau
|
||||
WebSocket normal, buat [plugin provider](/id/plugins/sdk-provider-plugins).
|
||||
WebSocket normal, bangun [plugin provider](/id/plugins/sdk-provider-plugins).
|
||||
|
||||
## Apa yang masih dimiliki core
|
||||
## Yang masih dimiliki core
|
||||
|
||||
Sebelum harness dipilih, OpenClaw sudah menyelesaikan:
|
||||
Sebelum sebuah harness dipilih, OpenClaw sudah menyelesaikan:
|
||||
|
||||
- provider dan model
|
||||
- penyedia dan model
|
||||
- status auth runtime
|
||||
- tingkat thinking dan anggaran konteks
|
||||
- tingkat berpikir dan anggaran konteks
|
||||
- file transkrip/sesi OpenClaw
|
||||
- workspace, sandbox, dan kebijakan alat
|
||||
- callback balasan saluran dan callback streaming
|
||||
- kebijakan fallback model dan perpindahan model live
|
||||
- workspace, sandbox, dan kebijakan tool
|
||||
- callback balasan channel dan callback streaming
|
||||
- kebijakan fallback model dan peralihan model live
|
||||
|
||||
Pemisahan itu disengaja. Harness menjalankan upaya yang sudah disiapkan; harness tidak memilih
|
||||
provider, mengganti pengiriman saluran, atau diam-diam mengganti model.
|
||||
Pemisahan itu disengaja. Sebuah harness menjalankan upaya yang sudah disiapkan;
|
||||
ia tidak memilih penyedia, menggantikan pengiriman channel, atau diam-diam
|
||||
mengganti model.
|
||||
|
||||
## Mendaftarkan harness
|
||||
## Daftarkan harness
|
||||
|
||||
**Import:** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -73,9 +73,9 @@ const myHarness: AgentHarness = {
|
||||
},
|
||||
|
||||
async runAttempt(params) {
|
||||
// Mulai atau lanjutkan thread native Anda.
|
||||
// Gunakan params.prompt, params.tools, params.images, params.onPartialReply,
|
||||
// params.onAgentEvent, dan field upaya siap pakai lainnya.
|
||||
// Start or resume your native thread.
|
||||
// Use params.prompt, params.tools, params.images, params.onPartialReply,
|
||||
// params.onAgentEvent, and the other prepared attempt fields.
|
||||
return await runMyNativeTurn(params);
|
||||
},
|
||||
};
|
||||
@ -96,62 +96,81 @@ OpenClaw memilih harness setelah resolusi provider/model:
|
||||
|
||||
1. `OPENCLAW_AGENT_RUNTIME=<id>` memaksa harness terdaftar dengan id tersebut.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=pi` memaksa harness PI bawaan.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` meminta harness terdaftar apakah mereka mendukung
|
||||
provider/model yang telah diselesaikan.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` meminta harness terdaftar apakah mereka mendukung provider/model
|
||||
yang telah diselesaikan.
|
||||
4. Jika tidak ada harness terdaftar yang cocok, OpenClaw menggunakan PI kecuali fallback PI
|
||||
dinonaktifkan.
|
||||
|
||||
Kegagalan harness plugin yang dipaksakan akan muncul sebagai kegagalan eksekusi. Dalam mode `auto`,
|
||||
Kegagalan harness plugin yang dipaksakan akan muncul sebagai kegagalan run. Dalam mode `auto`,
|
||||
OpenClaw dapat fallback ke PI ketika harness plugin terpilih gagal sebelum sebuah
|
||||
giliran menghasilkan efek samping. Setel `OPENCLAW_AGENT_HARNESS_FALLBACK=none` atau
|
||||
`embeddedHarness.fallback: "none"` untuk menjadikan fallback tersebut sebagai kegagalan keras.
|
||||
giliran menghasilkan efek samping. Tetapkan `OPENCLAW_AGENT_HARNESS_FALLBACK=none` atau
|
||||
`embeddedHarness.fallback: "none"` agar fallback itu menjadi kegagalan keras.
|
||||
|
||||
Plugin Codex terbundel mendaftarkan `codex` sebagai id harness-nya. Core memperlakukan itu
|
||||
Plugin Codex bawaan mendaftarkan `codex` sebagai harness id-nya. Core memperlakukan itu
|
||||
sebagai id harness plugin biasa; alias khusus Codex harus berada di plugin
|
||||
atau config operator, bukan di pemilih runtime bersama.
|
||||
atau konfigurasi operator, bukan di selector runtime bersama.
|
||||
|
||||
## Penyandingan provider dan harness
|
||||
## Pairing provider plus harness
|
||||
|
||||
Sebagian besar harness juga sebaiknya mendaftarkan provider. Provider membuat referensi model,
|
||||
status auth, metadata model, dan pemilihan `/model` terlihat oleh bagian lain dari
|
||||
Sebagian besar harness juga sebaiknya mendaftarkan provider. Provider membuat ref model,
|
||||
status auth, metadata model, dan pemilihan `/model` terlihat oleh seluruh
|
||||
OpenClaw. Harness kemudian mengklaim provider itu di `supports(...)`.
|
||||
|
||||
Plugin Codex terbundel mengikuti pola ini:
|
||||
Plugin Codex bawaan mengikuti pola ini:
|
||||
|
||||
- id provider: `codex`
|
||||
- referensi model pengguna: `codex/gpt-5.4`, `codex/gpt-5.2`, atau model lain yang dikembalikan
|
||||
- provider id: `codex`
|
||||
- ref model pengguna: `codex/gpt-5.4`, `codex/gpt-5.2`, atau model lain yang dikembalikan
|
||||
oleh server aplikasi Codex
|
||||
- id harness: `codex`
|
||||
- harness id: `codex`
|
||||
- auth: ketersediaan provider sintetis, karena harness Codex memiliki
|
||||
login/sesi Codex native
|
||||
- permintaan app-server: OpenClaw mengirim id model mentah ke Codex dan membiarkan
|
||||
- permintaan app-server: OpenClaw mengirim bare model id ke Codex dan membiarkan
|
||||
harness berbicara dengan protokol app-server native
|
||||
|
||||
Plugin Codex bersifat aditif. Referensi `openai/gpt-*` biasa tetap merupakan referensi provider OpenAI
|
||||
Plugin Codex bersifat aditif. Ref `openai/gpt-*` biasa tetap menjadi ref provider OpenAI
|
||||
dan terus menggunakan jalur provider OpenClaw normal. Pilih `codex/gpt-*`
|
||||
ketika Anda menginginkan auth yang dikelola Codex, penemuan model Codex, thread native, dan
|
||||
eksekusi app-server Codex. `/model` dapat berpindah di antara model Codex yang dikembalikan
|
||||
oleh app-server Codex tanpa memerlukan kredensial provider OpenAI.
|
||||
saat Anda menginginkan auth yang dikelola Codex, penemuan model Codex, thread native, dan
|
||||
eksekusi app-server Codex. `/model` dapat beralih di antara model Codex yang
|
||||
dikembalikan oleh app-server Codex tanpa memerlukan kredensial provider OpenAI.
|
||||
|
||||
Untuk penyiapan operator, contoh prefix model, dan config khusus Codex, lihat
|
||||
Untuk penyiapan operator, contoh prefiks model, dan konfigurasi khusus Codex, lihat
|
||||
[Codex Harness](/id/plugins/codex-harness).
|
||||
|
||||
OpenClaw memerlukan app-server Codex `0.118.0` atau yang lebih baru. Plugin Codex memeriksa
|
||||
handshake inisialisasi app-server dan memblokir server yang lebih lama atau tanpa versi sehingga
|
||||
initialize handshake app-server dan memblokir server yang lebih lama atau tanpa versi agar
|
||||
OpenClaw hanya berjalan terhadap permukaan protokol yang telah diuji.
|
||||
|
||||
### Mode harness Codex native
|
||||
|
||||
Harness `codex` bawaan adalah mode Codex native untuk giliran agen OpenClaw
|
||||
tertanam. Aktifkan plugin `codex` bawaan terlebih dahulu, dan sertakan `codex` di
|
||||
`plugins.allow` jika konfigurasi Anda menggunakan allowlist yang ketat. Ini berbeda
|
||||
dari `openai-codex/*`:
|
||||
|
||||
- `openai-codex/*` menggunakan OAuth ChatGPT/Codex melalui jalur provider OpenClaw normal.
|
||||
- `codex/*` menggunakan provider Codex bawaan dan merutekan giliran melalui Codex
|
||||
app-server.
|
||||
|
||||
Saat mode ini berjalan, Codex memiliki thread id native, perilaku resume,
|
||||
compaction, dan eksekusi app-server. OpenClaw tetap memiliki channel chat,
|
||||
mirror transkrip yang terlihat, kebijakan tool, persetujuan, pengiriman media, dan
|
||||
pemilihan sesi. Gunakan `embeddedHarness.runtime: "codex"` dengan
|
||||
`embeddedHarness.fallback: "none"` saat Anda perlu membuktikan bahwa jalur
|
||||
app-server Codex digunakan dan fallback PI tidak menyembunyikan harness native yang rusak.
|
||||
|
||||
## Nonaktifkan fallback PI
|
||||
|
||||
Secara default, OpenClaw menjalankan agen tertanam dengan `agents.defaults.embeddedHarness`
|
||||
disetel ke `{ runtime: "auto", fallback: "pi" }`. Dalam mode `auto`, plugin
|
||||
harness yang terdaftar dapat mengklaim pasangan provider/model. Jika tidak ada yang cocok, atau jika harness plugin yang dipilih otomatis
|
||||
gagal sebelum menghasilkan output, OpenClaw fallback ke PI.
|
||||
diatur ke `{ runtime: "auto", fallback: "pi" }`. Dalam mode `auto`, plugin
|
||||
harness yang terdaftar dapat mengklaim pasangan provider/model. Jika tidak ada yang cocok,
|
||||
atau jika harness plugin yang dipilih otomatis gagal sebelum menghasilkan output,
|
||||
OpenClaw fallback ke PI.
|
||||
|
||||
Setel `fallback: "none"` ketika Anda perlu membuktikan bahwa harness plugin adalah satu-satunya
|
||||
runtime yang sedang digunakan. Ini menonaktifkan fallback PI otomatis; ini tidak memblokir
|
||||
Tetapkan `fallback: "none"` saat Anda perlu membuktikan bahwa harness plugin adalah satu-satunya
|
||||
runtime yang sedang diuji. Ini menonaktifkan fallback PI otomatis; ini tidak memblokir
|
||||
`runtime: "pi"` yang eksplisit atau `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Untuk eksekusi tertanam khusus Codex:
|
||||
Untuk run tertanam khusus Codex:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -219,48 +238,48 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Dengan fallback dinonaktifkan, sesi gagal lebih awal ketika harness yang diminta tidak
|
||||
Dengan fallback dinonaktifkan, sebuah sesi gagal lebih awal saat harness yang diminta tidak
|
||||
terdaftar, tidak mendukung provider/model yang telah diselesaikan, atau gagal sebelum
|
||||
menghasilkan efek samping giliran. Ini disengaja untuk deployment khusus Codex dan
|
||||
untuk live test yang harus membuktikan jalur app-server Codex benar-benar digunakan.
|
||||
untuk live test yang harus membuktikan bahwa jalur app-server Codex benar-benar digunakan.
|
||||
|
||||
Pengaturan ini hanya mengontrol harness agen tertanam. Ini tidak menonaktifkan
|
||||
perutean model khusus provider untuk image, video, music, TTS, PDF, atau lainnya.
|
||||
perutean model khusus provider untuk gambar, video, musik, TTS, PDF, atau yang lainnya.
|
||||
|
||||
## Sesi native dan mirror transkrip
|
||||
|
||||
Harness dapat menyimpan id sesi native, id thread, atau token resume sisi daemon.
|
||||
Pertahankan keterikatan itu secara eksplisit terkait dengan sesi OpenClaw, dan terus
|
||||
mirror output asisten/alat yang terlihat pengguna ke dalam transkrip OpenClaw.
|
||||
Sebuah harness dapat menyimpan session id native, thread id, atau token resume di sisi daemon.
|
||||
Pertahankan pengikatan itu secara eksplisit terkait dengan sesi OpenClaw, dan tetap
|
||||
mirror output asisten/tool yang terlihat oleh pengguna ke dalam transkrip OpenClaw.
|
||||
|
||||
Transkrip OpenClaw tetap menjadi lapisan kompatibilitas untuk:
|
||||
|
||||
- riwayat sesi yang terlihat di saluran
|
||||
- riwayat sesi yang terlihat di channel
|
||||
- pencarian dan pengindeksan transkrip
|
||||
- beralih kembali ke harness PI bawaan pada giliran berikutnya
|
||||
- perilaku generik `/new`, `/reset`, dan penghapusan sesi
|
||||
- perilaku `/new`, `/reset`, dan penghapusan sesi generik
|
||||
|
||||
Jika harness Anda menyimpan sidecar binding, implementasikan `reset(...)` agar OpenClaw dapat
|
||||
menghapusnya ketika sesi OpenClaw pemilik di-reset.
|
||||
menghapusnya saat sesi OpenClaw pemilik di-reset.
|
||||
|
||||
## Hasil alat dan media
|
||||
## Hasil tool dan media
|
||||
|
||||
Core membangun daftar alat OpenClaw dan meneruskannya ke upaya yang sudah disiapkan.
|
||||
Saat harness mengeksekusi pemanggilan alat dinamis, kembalikan hasil alat melalui
|
||||
bentuk hasil harness alih-alih mengirim media saluran sendiri.
|
||||
Core membangun daftar tool OpenClaw dan meneruskannya ke upaya yang sudah disiapkan.
|
||||
Saat sebuah harness mengeksekusi pemanggilan tool dinamis, kembalikan hasil tool melalui
|
||||
bentuk hasil harness alih-alih mengirim media channel sendiri.
|
||||
|
||||
Ini menjaga output text, image, video, music, TTS, persetujuan, dan alat pesan
|
||||
tetap pada jalur pengiriman yang sama seperti eksekusi berbasis PI.
|
||||
Ini menjaga output teks, gambar, video, musik, TTS, persetujuan, dan tool perpesanan
|
||||
tetap berada pada jalur pengiriman yang sama seperti run berbasis PI.
|
||||
|
||||
## Keterbatasan saat ini
|
||||
## Batasan saat ini
|
||||
|
||||
- Jalur import publik bersifat generik, tetapi beberapa alias tipe upaya/hasil masih
|
||||
membawa nama `Pi` untuk kompatibilitas.
|
||||
- Instalasi harness pihak ketiga bersifat eksperimental. Pilih plugin provider
|
||||
sampai Anda membutuhkan runtime sesi native.
|
||||
- Perpindahan harness didukung antar giliran. Jangan mengganti harness di
|
||||
tengah giliran setelah alat native, persetujuan, text asisten, atau pengiriman
|
||||
pesan dimulai.
|
||||
- Jalur import publik bersifat generik, tetapi beberapa alias tipe attempt/result masih
|
||||
membawa nama `Pi` demi kompatibilitas.
|
||||
- Pemasangan harness pihak ketiga masih eksperimental. Utamakan plugin provider
|
||||
sampai Anda memerlukan runtime sesi native.
|
||||
- Peralihan harness didukung antar giliran. Jangan mengganti harness di tengah
|
||||
giliran setelah tool native, persetujuan, teks asisten, atau pengiriman
|
||||
pesan telah dimulai.
|
||||
|
||||
## Terkait
|
||||
|
||||
|
||||
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda ingin menggunakan model OpenAI di OpenClaw
|
||||
- Anda menginginkan autentikasi langganan Codex alih-alih API key
|
||||
summary: Gunakan OpenAI melalui API key atau langganan Codex di OpenClaw
|
||||
- Anda ingin autentikasi langganan Codex alih-alih kunci API
|
||||
- Anda memerlukan perilaku eksekusi agen GPT-5 yang lebih ketat
|
||||
summary: Gunakan OpenAI melalui kunci API atau langganan Codex di OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:19:29Z"
|
||||
generated_at: "2026-04-12T00:18:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a2ce1ce5f085fe55ec50b8d20359180b9002c9730820cd5b0e011c3bf807b64
|
||||
source_hash: 7aa06fba9ac901e663685a6b26443a2f6aeb6ec3589d939522dc87cbb43497b4
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenAI
|
||||
|
||||
OpenAI menyediakan API pengembang untuk model GPT. Codex mendukung **masuk dengan ChatGPT** untuk akses
|
||||
langganan atau **masuk dengan API key** untuk akses berbasis penggunaan. Codex cloud memerlukan masuk dengan ChatGPT.
|
||||
OpenAI menyediakan API pengembang untuk model GPT. Codex mendukung **masuk dengan ChatGPT** untuk akses berbasis langganan atau **masuk dengan kunci API** untuk akses berbasis penggunaan. Codex cloud memerlukan masuk dengan ChatGPT.
|
||||
OpenAI secara eksplisit mendukung penggunaan OAuth langganan di alat/alur kerja eksternal seperti OpenClaw.
|
||||
|
||||
## Gaya interaksi default
|
||||
|
||||
OpenClaw dapat menambahkan overlay prompt kecil khusus OpenAI untuk eksekusi `openai/*` dan
|
||||
`openai-codex/*`. Secara default, overlay ini membuat asisten tetap hangat,
|
||||
`openai-codex/*`. Secara default, overlay ini menjaga asisten tetap hangat,
|
||||
kolaboratif, ringkas, langsung, dan sedikit lebih ekspresif secara emosional
|
||||
tanpa menggantikan prompt sistem dasar OpenClaw. Overlay yang ramah ini juga
|
||||
mengizinkan emoji sesekali ketika terasa alami, sambil tetap menjaga
|
||||
output secara keseluruhan tetap ringkas.
|
||||
mengizinkan emoji sesekali bila terasa alami, sambil tetap menjaga keseluruhan
|
||||
output tetap ringkas.
|
||||
|
||||
Kunci config:
|
||||
Kunci konfigurasi:
|
||||
|
||||
`plugins.entries.openai.config.personality`
|
||||
|
||||
@ -44,8 +44,8 @@ Cakupan:
|
||||
- Berlaku untuk model `openai-codex/*`.
|
||||
- Tidak memengaruhi provider lain.
|
||||
|
||||
Perilaku ini aktif secara default. Tetap gunakan `"friendly"` secara eksplisit jika Anda ingin itu
|
||||
bertahan dari perubahan config lokal di masa mendatang:
|
||||
Perilaku ini aktif secara default. Tetapkan `"friendly"` secara eksplisit jika Anda ingin
|
||||
pengaturan ini tetap bertahan dari perubahan konfigurasi lokal di masa mendatang:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -61,9 +61,9 @@ bertahan dari perubahan config lokal di masa mendatang:
|
||||
}
|
||||
```
|
||||
|
||||
### Nonaktifkan overlay prompt OpenAI
|
||||
### Menonaktifkan overlay prompt OpenAI
|
||||
|
||||
Jika Anda menginginkan prompt dasar OpenClaw yang tidak dimodifikasi, set overlay ke `"off"`:
|
||||
Jika Anda ingin prompt dasar OpenClaw yang tidak dimodifikasi, atur overlay ke `"off"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -79,27 +79,27 @@ Jika Anda menginginkan prompt dasar OpenClaw yang tidak dimodifikasi, set overla
|
||||
}
|
||||
```
|
||||
|
||||
Anda juga dapat menyetelnya langsung dengan config CLI:
|
||||
Anda juga dapat mengaturnya langsung dengan CLI konfigurasi:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.openai.config.personality off
|
||||
```
|
||||
|
||||
OpenClaw menormalisasi pengaturan ini secara case-insensitive saat runtime, sehingga nilai seperti
|
||||
OpenClaw menormalkan pengaturan ini secara case-insensitive saat runtime, sehingga nilai seperti
|
||||
`"Off"` tetap menonaktifkan overlay ramah.
|
||||
|
||||
## Opsi A: API key OpenAI (OpenAI Platform)
|
||||
## Opsi A: kunci API OpenAI (OpenAI Platform)
|
||||
|
||||
**Paling cocok untuk:** akses API langsung dan penagihan berbasis penggunaan.
|
||||
Dapatkan API key Anda dari dashboard OpenAI.
|
||||
**Terbaik untuk:** akses API langsung dan penagihan berbasis penggunaan.
|
||||
Dapatkan kunci API Anda dari dashboard OpenAI.
|
||||
|
||||
Ringkasan rute:
|
||||
|
||||
- `openai/gpt-5.4` = rute API OpenAI Platform langsung
|
||||
- Memerlukan `OPENAI_API_KEY` (atau config provider OpenAI yang setara)
|
||||
- Memerlukan `OPENAI_API_KEY` (atau konfigurasi provider OpenAI yang setara)
|
||||
- Di OpenClaw, masuk ChatGPT/Codex dirutekan melalui `openai-codex/*`, bukan `openai/*`
|
||||
|
||||
### Setup CLI
|
||||
### Penyiapan CLI
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
@ -107,7 +107,7 @@ openclaw onboard --auth-choice openai-api-key
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
### Cuplikan config
|
||||
### Potongan konfigurasi
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -116,25 +116,25 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
}
|
||||
```
|
||||
|
||||
Dokumentasi model API OpenAI saat ini mencantumkan `gpt-5.4` dan `gpt-5.4-pro` untuk penggunaan
|
||||
API OpenAI langsung. OpenClaw meneruskan keduanya melalui jalur `openai/*` Responses.
|
||||
OpenClaw dengan sengaja menyembunyikan baris `openai/gpt-5.3-codex-spark` yang sudah usang,
|
||||
karena panggilan API OpenAI langsung menolaknya dalam traffic langsung.
|
||||
Dokumentasi model API OpenAI saat ini mencantumkan `gpt-5.4` dan `gpt-5.4-pro` untuk penggunaan API OpenAI
|
||||
langsung. OpenClaw meneruskan keduanya melalui jalur Responses `openai/*`.
|
||||
OpenClaw sengaja menyembunyikan baris lama `openai/gpt-5.3-codex-spark`,
|
||||
karena panggilan API OpenAI langsung menolaknya pada lalu lintas live.
|
||||
|
||||
OpenClaw **tidak** mengekspos `openai/gpt-5.3-codex-spark` pada jalur API OpenAI
|
||||
langsung. `pi-ai` masih mengirimkan baris bawaan untuk model itu, tetapi permintaan API OpenAI langsung
|
||||
saat ini menolaknya. Spark diperlakukan hanya untuk Codex di OpenClaw.
|
||||
OpenClaw **tidak** mengekspos `openai/gpt-5.3-codex-spark` pada jalur OpenAI
|
||||
API langsung. `pi-ai` masih mengirimkan baris bawaan untuk model itu, tetapi permintaan OpenAI API live
|
||||
saat ini menolaknya. Spark diperlakukan sebagai khusus Codex di OpenClaw.
|
||||
|
||||
## Pembuatan gambar
|
||||
|
||||
Plugin `openai` bawaan juga mendaftarkan pembuatan gambar melalui tool bersama
|
||||
`image_generate`.
|
||||
Plugin `openai` bawaan juga mendaftarkan pembuatan gambar melalui
|
||||
tool `image_generate` bersama.
|
||||
|
||||
- Model gambar default: `openai/gpt-image-1`
|
||||
- Hasilkan: hingga 4 gambar per permintaan
|
||||
- Mode edit: aktif, hingga 5 gambar referensi
|
||||
- Mode edit: diaktifkan, hingga 5 gambar referensi
|
||||
- Mendukung `size`
|
||||
- Catatan khusus OpenAI saat ini: OpenClaw belum meneruskan override `aspectRatio` atau
|
||||
- Peringatan khusus OpenAI saat ini: OpenClaw tidak meneruskan override `aspectRatio` atau
|
||||
`resolution` ke OpenAI Images API saat ini
|
||||
|
||||
Untuk menggunakan OpenAI sebagai provider gambar default:
|
||||
@ -151,18 +151,18 @@ Untuk menggunakan OpenAI sebagai provider gambar default:
|
||||
}
|
||||
```
|
||||
|
||||
Lihat [Image Generation](/id/tools/image-generation) untuk parameter
|
||||
Lihat [Pembuatan Gambar](/id/tools/image-generation) untuk parameter
|
||||
tool bersama, pemilihan provider, dan perilaku failover.
|
||||
|
||||
## Pembuatan video
|
||||
|
||||
Plugin `openai` bawaan juga mendaftarkan pembuatan video melalui tool bersama
|
||||
`video_generate`.
|
||||
Plugin `openai` bawaan juga mendaftarkan pembuatan video melalui tool
|
||||
`video_generate` bersama.
|
||||
|
||||
- Model video default: `openai/sora-2`
|
||||
- Mode: text-to-video, image-to-video, dan alur referensi/edit video tunggal
|
||||
- Batas saat ini: 1 gambar atau 1 input referensi video
|
||||
- Catatan khusus OpenAI saat ini: OpenClaw saat ini hanya meneruskan override `size`
|
||||
- Mode: text-to-video, image-to-video, dan alur referensi/edit satu video
|
||||
- Batas saat ini: 1 input referensi gambar atau 1 video
|
||||
- Peringatan khusus OpenAI saat ini: OpenClaw saat ini hanya meneruskan override `size`
|
||||
untuk pembuatan video OpenAI native. Override opsional yang tidak didukung
|
||||
seperti `aspectRatio`, `resolution`, `audio`, dan `watermark` diabaikan
|
||||
dan dilaporkan kembali sebagai peringatan tool.
|
||||
@ -181,21 +181,21 @@ Untuk menggunakan OpenAI sebagai provider video default:
|
||||
}
|
||||
```
|
||||
|
||||
Lihat [Video Generation](/id/tools/video-generation) untuk parameter
|
||||
Lihat [Pembuatan Video](/id/tools/video-generation) untuk parameter
|
||||
tool bersama, pemilihan provider, dan perilaku failover.
|
||||
|
||||
## Opsi B: langganan OpenAI Code (Codex)
|
||||
|
||||
**Paling cocok untuk:** menggunakan akses langganan ChatGPT/Codex alih-alih API key.
|
||||
Codex cloud memerlukan masuk dengan ChatGPT, sedangkan Codex CLI mendukung masuk dengan ChatGPT atau API key.
|
||||
**Terbaik untuk:** menggunakan akses langganan ChatGPT/Codex alih-alih kunci API.
|
||||
Codex cloud memerlukan masuk dengan ChatGPT, sedangkan CLI Codex mendukung masuk dengan ChatGPT atau kunci API.
|
||||
|
||||
Ringkasan rute:
|
||||
|
||||
- `openai-codex/gpt-5.4` = rute OAuth ChatGPT/Codex
|
||||
- Menggunakan masuk dengan ChatGPT/Codex, bukan API key OpenAI Platform langsung
|
||||
- Menggunakan masuk ChatGPT/Codex, bukan kunci API OpenAI Platform langsung
|
||||
- Batas di sisi provider untuk `openai-codex/*` dapat berbeda dari pengalaman web/aplikasi ChatGPT
|
||||
|
||||
### Setup CLI (Codex OAuth)
|
||||
### Penyiapan CLI (Codex OAuth)
|
||||
|
||||
```bash
|
||||
# Jalankan Codex OAuth di wizard
|
||||
@ -205,7 +205,7 @@ openclaw onboard --auth-choice openai-codex
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
### Cuplikan config (langganan Codex)
|
||||
### Potongan konfigurasi (langganan Codex)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -214,33 +214,32 @@ openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
Dokumentasi Codex OpenAI saat ini mencantumkan `gpt-5.4` sebagai model Codex saat ini. OpenClaw
|
||||
memetakan itu ke `openai-codex/gpt-5.4` untuk penggunaan OAuth ChatGPT/Codex.
|
||||
memetakannya ke `openai-codex/gpt-5.4` untuk penggunaan OAuth ChatGPT/Codex.
|
||||
|
||||
Rute ini sengaja dipisahkan dari `openai/gpt-5.4`. Jika Anda ingin jalur API OpenAI Platform
|
||||
langsung, gunakan `openai/*` dengan API key. Jika Anda ingin
|
||||
masuk dengan ChatGPT/Codex, gunakan `openai-codex/*`.
|
||||
Rute ini sengaja dipisahkan dari `openai/gpt-5.4`. Jika Anda menginginkan
|
||||
jalur API OpenAI Platform langsung, gunakan `openai/*` dengan kunci API. Jika Anda menginginkan
|
||||
masuk ChatGPT/Codex, gunakan `openai-codex/*`.
|
||||
|
||||
Jika onboarding menggunakan kembali login Codex CLI yang sudah ada, kredensial tersebut tetap
|
||||
dikelola oleh Codex CLI. Saat kedaluwarsa, OpenClaw membaca ulang sumber Codex eksternal
|
||||
terlebih dahulu dan, ketika provider dapat menyegarkannya, menulis kembali kredensial yang disegarkan
|
||||
ke penyimpanan Codex alih-alih mengambil alih kepemilikan dalam salinan terpisah khusus OpenClaw.
|
||||
Jika onboarding menggunakan kembali login CLI Codex yang sudah ada, kredensial tersebut tetap
|
||||
dikelola oleh CLI Codex. Saat kedaluwarsa, OpenClaw membaca ulang sumber Codex eksternal
|
||||
terlebih dahulu dan, ketika provider dapat me-refresh-nya, menulis kredensial yang telah diperbarui
|
||||
kembali ke penyimpanan Codex alih-alih mengambil alih kepemilikan dalam salinan terpisah khusus OpenClaw.
|
||||
|
||||
Jika akun Codex Anda memiliki hak atas Codex Spark, OpenClaw juga mendukung:
|
||||
Jika akun Codex Anda berhak atas Codex Spark, OpenClaw juga mendukung:
|
||||
|
||||
- `openai-codex/gpt-5.3-codex-spark`
|
||||
|
||||
OpenClaw memperlakukan Codex Spark sebagai khusus Codex. OpenClaw tidak mengekspos jalur API key langsung
|
||||
`openai/gpt-5.3-codex-spark`.
|
||||
OpenClaw memperlakukan Codex Spark sebagai khusus Codex. OpenClaw tidak mengekspos
|
||||
jalur kunci API `openai/gpt-5.3-codex-spark` langsung.
|
||||
|
||||
OpenClaw juga mempertahankan `openai-codex/gpt-5.3-codex-spark` ketika `pi-ai`
|
||||
menemukannya. Perlakukan ini sebagai bergantung pada entitlement dan eksperimental: Codex Spark terpisah
|
||||
dari GPT-5.4 `/fast`, dan ketersediaannya bergantung pada akun Codex /
|
||||
OpenClaw juga mempertahankan `openai-codex/gpt-5.3-codex-spark` saat `pi-ai`
|
||||
menemukannya. Perlakukan ini sebagai bergantung pada entitlement dan eksperimental: Codex Spark
|
||||
terpisah dari GPT-5.4 `/fast`, dan ketersediaannya bergantung pada akun Codex /
|
||||
ChatGPT yang sedang masuk.
|
||||
|
||||
### Batas jendela konteks Codex
|
||||
|
||||
OpenClaw memperlakukan metadata model Codex dan batas konteks runtime sebagai nilai
|
||||
yang terpisah.
|
||||
OpenClaw memperlakukan metadata model Codex dan batas konteks runtime sebagai nilai yang terpisah.
|
||||
|
||||
Untuk `openai-codex/gpt-5.4`:
|
||||
|
||||
@ -250,7 +249,7 @@ Untuk `openai-codex/gpt-5.4`:
|
||||
Ini menjaga metadata model tetap akurat sambil mempertahankan jendela runtime default yang lebih kecil
|
||||
yang dalam praktiknya memiliki karakteristik latensi dan kualitas yang lebih baik.
|
||||
|
||||
Jika Anda menginginkan batas efektif yang berbeda, set `models.providers.<provider>.models[].contextTokens`:
|
||||
Jika Anda menginginkan batas efektif yang berbeda, atur `models.providers.<provider>.models[].contextTokens`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,39 +268,36 @@ Jika Anda menginginkan batas efektif yang berbeda, set `models.providers.<provid
|
||||
}
|
||||
```
|
||||
|
||||
Gunakan `contextWindow` hanya ketika Anda mendeklarasikan atau mengganti metadata model
|
||||
native. Gunakan `contextTokens` ketika Anda ingin membatasi anggaran konteks runtime.
|
||||
Gunakan `contextWindow` hanya saat Anda mendeklarasikan atau menimpa metadata model
|
||||
native. Gunakan `contextTokens` saat Anda ingin membatasi anggaran konteks runtime.
|
||||
|
||||
### Default transport
|
||||
|
||||
OpenClaw menggunakan `pi-ai` untuk streaming model. Untuk `openai/*` dan
|
||||
`openai-codex/*`, transport default adalah `"auto"` (WebSocket-first, lalu fallback
|
||||
SSE).
|
||||
`openai-codex/*`, transport default adalah `"auto"` (WebSocket terlebih dahulu, lalu fallback SSE).
|
||||
|
||||
Dalam mode `"auto"`, OpenClaw juga mencoba ulang satu kegagalan WebSocket awal yang dapat dicoba ulang
|
||||
sebelum fallback ke SSE. Mode `"websocket"` yang dipaksakan tetap menampilkan error transport
|
||||
secara langsung alih-alih menyembunyikannya di balik fallback.
|
||||
sebelum beralih ke SSE. Mode `"websocket"` yang dipaksakan tetap menampilkan error transport secara langsung
|
||||
alih-alih menyembunyikannya di balik fallback.
|
||||
|
||||
Setelah kegagalan WebSocket saat koneksi atau giliran awal dalam mode `"auto"`, OpenClaw menandai
|
||||
jalur WebSocket sesi itu sebagai terdegradasi selama sekitar 60 detik dan mengirim
|
||||
giliran berikutnya melalui SSE selama masa cooldown alih-alih terus berpindah
|
||||
Setelah kegagalan koneksi atau kegagalan WebSocket di awal giliran dalam mode `"auto"`, OpenClaw menandai
|
||||
jalur WebSocket sesi tersebut sebagai menurun selama sekitar 60 detik dan mengirim
|
||||
giliran berikutnya melalui SSE selama masa pendinginan alih-alih terus berpindah-pindah
|
||||
antartransport.
|
||||
|
||||
Untuk endpoint keluarga OpenAI native (`openai/*`, `openai-codex/*`, dan Azure
|
||||
OpenAI Responses), OpenClaw juga melampirkan status identitas sesi dan giliran yang stabil
|
||||
ke permintaan agar retry, reconnect, dan fallback SSE tetap selaras dengan
|
||||
identitas percakapan yang sama. Pada rute keluarga OpenAI native ini, hal ini mencakup
|
||||
header identitas permintaan sesi/giliran yang stabil plus metadata transport yang sesuai.
|
||||
identitas percakapan yang sama. Pada rute keluarga OpenAI native ini, hal tersebut mencakup header identitas permintaan sesi/giliran yang stabil serta metadata transport yang sesuai.
|
||||
|
||||
OpenClaw juga menormalisasi penghitung penggunaan OpenAI di seluruh varian transport sebelum
|
||||
mencapai permukaan sesi/status. Traffic Responses OpenAI/Codex native dapat
|
||||
OpenClaw juga menormalkan penghitung penggunaan OpenAI di seluruh varian transport sebelum
|
||||
mencapai permukaan sesi/status. Lalu lintas Responses OpenAI/Codex native dapat
|
||||
melaporkan penggunaan sebagai `input_tokens` / `output_tokens` atau
|
||||
`prompt_tokens` / `completion_tokens`; OpenClaw memperlakukan keduanya sebagai penghitung input
|
||||
dan output yang sama untuk `/status`, `/usage`, dan log sesi. Ketika traffic
|
||||
WebSocket native tidak menyertakan `total_tokens` (atau melaporkan `0`), OpenClaw fallback ke
|
||||
total input + output yang telah dinormalisasi agar tampilan sesi/status tetap terisi.
|
||||
dan output yang sama untuk `/status`, `/usage`, dan log sesi. Saat lalu lintas WebSocket native
|
||||
menghilangkan `total_tokens` (atau melaporkan `0`), OpenClaw menggunakan fallback ke total input + output yang telah dinormalisasi agar tampilan sesi/status tetap terisi.
|
||||
|
||||
Anda dapat menyetel `agents.defaults.models.<provider/model>.params.transport`:
|
||||
Anda dapat mengatur `agents.defaults.models.<provider/model>.params.transport`:
|
||||
|
||||
- `"sse"`: paksa SSE
|
||||
- `"websocket"`: paksa WebSocket
|
||||
@ -310,10 +306,10 @@ Anda dapat menyetel `agents.defaults.models.<provider/model>.params.transport`:
|
||||
Untuk `openai/*` (Responses API), OpenClaw juga mengaktifkan warm-up WebSocket secara default
|
||||
(`openaiWsWarmup: true`) saat transport WebSocket digunakan.
|
||||
|
||||
Dokumentasi OpenAI terkait:
|
||||
Dokumen OpenAI terkait:
|
||||
|
||||
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
- [Realtime API dengan WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming respons API (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -337,7 +333,7 @@ Dokumentasi OpenAI terkait:
|
||||
Dokumentasi OpenAI menjelaskan warm-up sebagai opsional. OpenClaw mengaktifkannya secara default untuk
|
||||
`openai/*` guna mengurangi latensi giliran pertama saat menggunakan transport WebSocket.
|
||||
|
||||
### Nonaktifkan warm-up
|
||||
### Menonaktifkan warm-up
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -355,7 +351,7 @@ Dokumentasi OpenAI menjelaskan warm-up sebagai opsional. OpenClaw mengaktifkanny
|
||||
}
|
||||
```
|
||||
|
||||
### Aktifkan warm-up secara eksplisit
|
||||
### Mengaktifkan warm-up secara eksplisit
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -376,7 +372,7 @@ Dokumentasi OpenAI menjelaskan warm-up sebagai opsional. OpenClaw mengaktifkanny
|
||||
### Pemrosesan prioritas OpenAI dan Codex
|
||||
|
||||
API OpenAI mengekspos pemrosesan prioritas melalui `service_tier=priority`. Di
|
||||
OpenClaw, set `agents.defaults.models["<provider>/<model>"].params.serviceTier`
|
||||
OpenClaw, atur `agents.defaults.models["<provider>/<model>"].params.serviceTier`
|
||||
untuk meneruskan field tersebut pada endpoint Responses OpenAI/Codex native.
|
||||
|
||||
```json5
|
||||
@ -403,7 +399,7 @@ untuk meneruskan field tersebut pada endpoint Responses OpenAI/Codex native.
|
||||
Nilai yang didukung adalah `auto`, `default`, `flex`, dan `priority`.
|
||||
|
||||
OpenClaw meneruskan `params.serviceTier` ke permintaan Responses `openai/*`
|
||||
langsung dan permintaan Codex Responses `openai-codex/*` ketika model tersebut mengarah
|
||||
langsung dan ke permintaan Codex Responses `openai-codex/*` saat model tersebut menunjuk
|
||||
ke endpoint OpenAI/Codex native.
|
||||
|
||||
Perilaku penting:
|
||||
@ -418,7 +414,7 @@ OpenClaw mengekspos toggle mode cepat bersama untuk sesi `openai/*` dan
|
||||
`openai-codex/*`:
|
||||
|
||||
- Chat/UI: `/fast status|on|off`
|
||||
- Config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
- Konfigurasi: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Saat mode cepat diaktifkan, OpenClaw memetakannya ke pemrosesan prioritas OpenAI:
|
||||
|
||||
@ -427,11 +423,11 @@ Saat mode cepat diaktifkan, OpenClaw memetakannya ke pemrosesan prioritas OpenAI
|
||||
- nilai `service_tier` payload yang sudah ada dipertahankan
|
||||
- mode cepat tidak menulis ulang `reasoning` atau `text.verbosity`
|
||||
|
||||
Khusus untuk GPT 5.4, setup yang paling umum adalah:
|
||||
Khusus untuk GPT 5.4, penyiapan yang paling umum adalah:
|
||||
|
||||
- kirim `/fast on` dalam sesi yang menggunakan `openai/gpt-5.4` atau `openai-codex/gpt-5.4`
|
||||
- atau set `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- jika Anda juga menggunakan Codex OAuth, set `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` juga
|
||||
- atau atur `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- jika Anda juga menggunakan OAuth Codex, atur `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` juga
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -456,48 +452,75 @@ Contoh:
|
||||
}
|
||||
```
|
||||
|
||||
Override sesi lebih diutamakan daripada config. Menghapus override sesi di UI Sessions
|
||||
mengembalikan sesi ke default yang dikonfigurasi.
|
||||
Override sesi lebih diprioritaskan daripada konfigurasi. Menghapus override sesi di UI Sessions
|
||||
akan mengembalikan sesi ke default yang dikonfigurasi.
|
||||
|
||||
### OpenAI native versus rute yang kompatibel dengan OpenAI
|
||||
### Rute OpenAI native versus OpenAI-compatible
|
||||
|
||||
OpenClaw memperlakukan endpoint OpenAI, Codex, dan Azure OpenAI langsung secara berbeda
|
||||
dari proxy `/v1` generik yang kompatibel dengan OpenAI:
|
||||
dari proxy `/v1` OpenAI-compatible generik:
|
||||
|
||||
- rute `openai/*`, `openai-codex/*`, dan Azure OpenAI native mempertahankan
|
||||
- rute native `openai/*`, `openai-codex/*`, dan Azure OpenAI mempertahankan
|
||||
`reasoning: { effort: "none" }` apa adanya saat Anda secara eksplisit menonaktifkan reasoning
|
||||
- rute keluarga OpenAI native menggunakan mode strict untuk skema tool secara default
|
||||
- rute keluarga OpenAI native menggunakan mode strict sebagai default untuk schema tool
|
||||
- header atribusi OpenClaw tersembunyi (`originator`, `version`, dan
|
||||
`User-Agent`) hanya dilampirkan pada host OpenAI native yang terverifikasi
|
||||
`User-Agent`) hanya dilampirkan pada host OpenAI native terverifikasi
|
||||
(`api.openai.com`) dan host Codex native (`chatgpt.com/backend-api`)
|
||||
- rute OpenAI/Codex native mempertahankan pembentukan permintaan khusus OpenAI seperti
|
||||
`service_tier`, Responses `store`, payload kompatibilitas reasoning OpenAI, dan
|
||||
petunjuk prompt-cache
|
||||
- rute bergaya proxy yang kompatibel dengan OpenAI mempertahankan perilaku kompatibilitas yang lebih longgar dan
|
||||
tidak memaksakan skema tool strict, pembentukan permintaan khusus native, atau header atribusi OpenAI/Codex tersembunyi
|
||||
- rute OpenAI-compatible bergaya proxy mempertahankan perilaku kompatibilitas yang lebih longgar dan
|
||||
tidak memaksakan schema tool strict, pembentukan permintaan khusus native, atau header
|
||||
atribusi OpenAI/Codex tersembunyi
|
||||
|
||||
Azure OpenAI tetap berada dalam kelompok perutean native untuk perilaku transport dan kompatibilitas,
|
||||
Azure OpenAI tetap berada dalam kelompok rute native untuk perilaku transport dan kompatibilitas,
|
||||
tetapi tidak menerima header atribusi OpenAI/Codex tersembunyi.
|
||||
|
||||
Ini mempertahankan perilaku OpenAI Responses native saat ini tanpa memaksakan shim kompatibilitas
|
||||
OpenAI yang lebih lama ke backend `/v1` pihak ketiga.
|
||||
Ini mempertahankan perilaku OpenAI Responses native saat ini tanpa memaksakan shim
|
||||
OpenAI-compatible lama ke backend `/v1` pihak ketiga.
|
||||
|
||||
### Pemadatan sisi server OpenAI Responses
|
||||
### Mode GPT agentik ketat
|
||||
|
||||
Untuk model OpenAI Responses langsung (`openai/*` menggunakan `api: "openai-responses"` dengan
|
||||
`baseUrl` pada `api.openai.com`), OpenClaw sekarang secara otomatis mengaktifkan petunjuk payload
|
||||
pemadatan sisi server OpenAI:
|
||||
Untuk eksekusi GPT keluarga-5 `openai/*` dan `openai-codex/*`, OpenClaw dapat menggunakan
|
||||
kontrak eksekusi Pi tertanam yang lebih ketat:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
embeddedPi: {
|
||||
executionContract: "strict-agentic",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Dengan `strict-agentic`, OpenClaw tidak lagi memperlakukan giliran asisten yang hanya berisi rencana sebagai
|
||||
kemajuan yang berhasil ketika tindakan tool konkret tersedia. OpenClaw akan mencoba ulang
|
||||
giliran tersebut dengan arahan bertindak sekarang, mengaktifkan otomatis tool `update_plan` terstruktur untuk
|
||||
pekerjaan yang substansial, dan menampilkan status terblokir yang eksplisit jika model terus
|
||||
membuat rencana tanpa bertindak.
|
||||
|
||||
Mode ini dibatasi untuk eksekusi GPT keluarga-5 OpenAI dan OpenAI Codex. Provider lain
|
||||
dan keluarga model yang lebih lama tetap menggunakan perilaku Pi tertanam default kecuali Anda memilih
|
||||
pengaturan runtime lain untuk mereka.
|
||||
|
||||
### Kompaksi sisi server OpenAI Responses
|
||||
|
||||
Untuk model OpenAI Responses langsung (`openai/*` yang menggunakan `api: "openai-responses"` dengan
|
||||
`baseUrl` pada `api.openai.com`), OpenClaw sekarang otomatis mengaktifkan petunjuk payload kompaksi sisi server OpenAI:
|
||||
|
||||
- Memaksa `store: true` (kecuali kompatibilitas model menetapkan `supportsStore: false`)
|
||||
- Menyuntikkan `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Menyisipkan `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
|
||||
Secara default, `compact_threshold` adalah `70%` dari `contextWindow` model (atau `80000`
|
||||
jika tidak tersedia).
|
||||
|
||||
### Aktifkan pemadatan sisi server secara eksplisit
|
||||
### Mengaktifkan kompaksi sisi server secara eksplisit
|
||||
|
||||
Gunakan ini ketika Anda ingin memaksa injeksi `context_management` pada model
|
||||
Responses yang kompatibel, misalnya Azure OpenAI Responses:
|
||||
Gunakan ini saat Anda ingin memaksa penyisipan `context_management` pada model
|
||||
Responses yang kompatibel (misalnya Azure OpenAI Responses):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -515,7 +538,7 @@ Responses yang kompatibel, misalnya Azure OpenAI Responses:
|
||||
}
|
||||
```
|
||||
|
||||
### Aktifkan dengan ambang kustom
|
||||
### Mengaktifkan dengan ambang khusus
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -534,7 +557,7 @@ Responses yang kompatibel, misalnya Azure OpenAI Responses:
|
||||
}
|
||||
```
|
||||
|
||||
### Nonaktifkan pemadatan sisi server
|
||||
### Menonaktifkan kompaksi sisi server
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -552,11 +575,11 @@ Responses yang kompatibel, misalnya Azure OpenAI Responses:
|
||||
}
|
||||
```
|
||||
|
||||
`responsesServerCompaction` hanya mengontrol injeksi `context_management`.
|
||||
`responsesServerCompaction` hanya mengontrol penyisipan `context_management`.
|
||||
Model OpenAI Responses langsung tetap memaksa `store: true` kecuali kompatibilitas menetapkan
|
||||
`supportsStore: false`.
|
||||
|
||||
## Catatan
|
||||
|
||||
- Referensi model selalu menggunakan `provider/model` (lihat [/concepts/models](/id/concepts/models)).
|
||||
- Detail auth + aturan penggunaan ulang ada di [/concepts/oauth](/id/concepts/oauth).
|
||||
- Detail autentikasi + aturan penggunaan ulang ada di [/concepts/oauth](/id/concepts/oauth).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user