diff --git a/docs/id/channels/msteams.md b/docs/id/channels/msteams.md index 6a42b9bed..c96bf8fcd 100644 --- a/docs/id/channels/msteams.md +++ b/docs/id/channels/msteams.md @@ -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: "", + tenantId: "", + 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: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Konfigurasi (user-assigned managed identity):** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + managedIdentityClientId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Env vars:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_USE_MANAGED_IDENTITY=true` +- `MSTEAMS_MANAGED_IDENTITY_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 --parameters '{ + "name": "my-bot-workload-identity", + "issuer": "", + "subject": "system:serviceaccount::", + "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: "" + ``` + +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 = `. - - 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://: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[""].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..replyStyle`: override per-team. - `channels.msteams.teams..requireMention`: override per-team. -- `channels.msteams.teams..tools`: override kebijakan tool default per-team (`allow`/`deny`/`alsoAllow`) yang digunakan saat override channel tidak ada. -- `channels.msteams.teams..toolsBySender`: override kebijakan tool per-pengirim default per-team (`"*"` wildcard didukung). -- `channels.msteams.teams..channels..replyStyle`: override per-channel. -- `channels.msteams.teams..channels..requireMention`: override per-channel. -- `channels.msteams.teams..channels..tools`: override kebijakan tool per-channel (`allow`/`deny`/`alsoAllow`). -- `channels.msteams.teams..channels..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..tools`: override kebijakan tool default per-team (`allow`/`deny`/`alsoAllow`) yang digunakan saat override saluran tidak ada. +- `channels.msteams.teams..toolsBySender`: override kebijakan tool default per-team per-pengirim (`"*"` wildcard didukung). +- `channels.msteams.teams..channels..replyStyle`: override per-saluran. +- `channels.msteams.teams..channels..requireMention`: override per-saluran. +- `channels.msteams.teams..channels..tools`: override kebijakan tool per-saluran (`allow`/`deny`/`alsoAllow`). +- `channels.msteams.teams..channels..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::`). - - Pesan channel/grup menggunakan ID percakapan: +- Kunci sesi mengikuti format agen standar (lihat [/concepts/session](/id/concepts/session)): + - Pesan langsung berbagi sesi utama (`agent::`). + - Pesan saluran/grup menggunakan ID percakapan: - `agent::msteams:channel:` - `agent::msteams:group:` -## 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: ...` -- 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:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | -| Pengguna (berdasarkan nama) | `user:` | `user:John Smith` (memerlukan Graph API) | -| Grup/channel | `conversation:` | `conversation:19:abc123...@thread.tacv2` | -| Grup/channel (mentah) | `` | `19:abc123...@thread.tacv2` (jika mengandung `@thread`) | +| Target type | Format | Example | +| ------------------- | -------------------------------- | --------------------------------------------------- | +| Pengguna (berdasarkan ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | +| Pengguna (berdasarkan nama) | `user:` | `user:John Smith` (memerlukan Graph API) | +| Grup/saluran | `conversation:` | `conversation:19:abc123...@thread.tacv2` | +| Grup/saluran (raw) | `` | `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 diff --git a/docs/id/plugins/sdk-agent-harness.md b/docs/id/plugins/sdk-agent-harness.md index 1791fd0ad..b26392e96 100644 --- a/docs/id/plugins/sdk-agent-harness.md +++ b/docs/id/plugins/sdk-agent-harness.md @@ -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=` 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 diff --git a/docs/id/providers/openai.md b/docs/id/providers/openai.md index 2edffbdee..bb39d206a 100644 --- a/docs/id/providers/openai.md +++ b/docs/id/providers/openai.md @@ -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..models[].contextTokens`: +Jika Anda menginginkan batas efektif yang berbeda, atur `models.providers..models[].contextTokens`: ```json5 { @@ -269,39 +268,36 @@ Jika Anda menginginkan batas efektif yang berbeda, set `models.providers..params.transport`: +Anda dapat mengatur `agents.defaults.models..params.transport`: - `"sse"`: paksa SSE - `"websocket"`: paksa WebSocket @@ -310,10 +306,10 @@ Anda dapat menyetel `agents.defaults.models..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["/"].params.serviceTier` +OpenClaw, atur `agents.defaults.models["/"].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["/"].params.fastMode` +- Konfigurasi: `agents.defaults.models["/"].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).