openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh id translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 18:42:10 +00:00
parent d988d36d85
commit c1da93ad49
5 changed files with 715 additions and 674 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

332
docs/id/ci.md
View File

@ -1,75 +1,75 @@
---
read_when:
- Anda perlu memahami mengapa sebuah tugas CI berjalan atau tidak berjalan
- Anda perlu memahami mengapa pekerjaan CI berjalan atau tidak berjalan
- Anda sedang men-debug pemeriksaan GitHub Actions yang gagal
- Anda sedang mengoordinasikan pelaksanaan atau pengulangan validasi rilis
- Anda sedang mengoordinasikan pelaksanaan atau pelaksanaan ulang validasi rilis
summary: Graf pekerjaan CI, gerbang cakupan, payung rilis, dan padanan perintah lokal
title: Alur CI
x-i18n:
generated_at: "2026-04-30T09:37:41Z"
generated_at: "2026-04-30T18:38:55Z"
model: gpt-5.5
provider: openai
source_hash: a9c18f0801864ca1030aac9ea81117b011bd7936388984a1809ce3ae6e906e62
source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd
source_path: ci.md
workflow: 16
---
OpenClaw CI berjalan pada setiap push ke `main` dan setiap pull request. Job `preflight` mengklasifikasikan diff dan mematikan lane mahal ketika hanya area yang tidak terkait berubah. Run manual `workflow_dispatch` secara sengaja melewati scope cerdas dan menyebarkan seluruh grafik untuk kandidat rilis dan validasi luas. Lane Android tetap opt-in melalui `include_android`. Cakupan Plugin khusus rilis berada di workflow [`Plugin Prerelease`](#plugin-prerelease) terpisah dan hanya berjalan dari [`Full Release Validation`](#full-release-validation) atau dispatch manual eksplisit.
OpenClaw CI berjalan pada setiap push ke `main` dan setiap pull request. Job `preflight` mengklasifikasikan diff dan menonaktifkan lane mahal ketika hanya area yang tidak terkait yang berubah. Run manual `workflow_dispatch` sengaja melewati smart scoping dan menyebarkan seluruh graph untuk kandidat rilis dan validasi luas. Lane Android tetap opt-in melalui `include_android`. Cakupan Plugin khusus rilis berada di workflow terpisah [`Plugin Prerelease`](#plugin-prerelease) dan hanya berjalan dari [`Full Release Validation`](#full-release-validation) atau dispatch manual eksplisit.
## Ikhtisar pipeline
## Gambaran umum pipeline
| Job | Tujuan | Kapan berjalan |
| -------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- |
| `preflight` | Mendeteksi perubahan khusus docs, scope yang berubah, extension yang berubah, dan membangun manifes CI | Selalu pada push dan PR non-draft |
| `security-scm-fast` | Deteksi kunci privat dan audit workflow melalui `zizmor` | Selalu pada push dan PR non-draft |
| `security-dependency-audit` | Audit lockfile produksi tanpa dependensi terhadap advisory npm | Selalu pada push dan PR non-draft |
| `security-fast` | Agregat wajib untuk job keamanan cepat | Selalu pada push dan PR non-draft |
| `check-dependencies` | Pass khusus dependensi Knip produksi ditambah guard allowlist file tidak terpakai | Perubahan yang relevan dengan Node |
| `build-artifacts` | Membangun `dist/`, Control UI, pemeriksaan artefak build, dan artefak downstream yang dapat digunakan ulang | Perubahan yang relevan dengan Node |
| `checks-fast-core` | Lane kebenaran Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan yang relevan dengan Node |
| `checks-fast-contracts-channels` | Pemeriksaan kontrak channel bershard dengan hasil pemeriksaan agregat stabil | Perubahan yang relevan dengan Node |
| `checks-node-core-test` | Shard pengujian Core Node, mengecualikan lane channel, bundled, contract, dan extension | Perubahan yang relevan dengan Node |
| `check` | Ekuivalen gate lokal utama bershard: tipe prod, lint, guard, tipe pengujian, dan smoke ketat | Perubahan yang relevan dengan Node |
| `check-additional` | Shard arsitektur, boundary, guard permukaan extension, package-boundary, dan gateway-watch | Perubahan yang relevan dengan Node |
| `build-smoke` | Pengujian smoke CLI yang sudah dibuild dan smoke memori startup | Perubahan yang relevan dengan Node |
| `checks` | Verifier untuk pengujian channel artefak build | Perubahan yang relevan dengan Node |
| `checks-node-compat-node22` | Lane build dan smoke kompatibilitas Node 22 | Dispatch CI manual untuk rilis |
| `check-docs` | Pemeriksaan format docs, lint, dan tautan rusak | Docs berubah |
| `skills-python` | Ruff + pytest untuk skill berbasis Python | Perubahan yang relevan dengan skill Python |
| `checks-windows` | Pengujian proses/path khusus Windows ditambah regresi specifier impor runtime bersama | Perubahan yang relevan dengan Windows |
| `macos-node` | Lane pengujian TypeScript macOS menggunakan artefak build bersama | Perubahan yang relevan dengan macOS |
| `macos-swift` | Lint, build, dan pengujian Swift untuk aplikasi macOS | Perubahan yang relevan dengan macOS |
| `android` | Pengujian unit Android untuk kedua flavor ditambah satu build APK debug | Perubahan yang relevan dengan Android |
| `test-performance-agent` | Optimasi pengujian lambat Codex harian setelah aktivitas tepercaya | CI utama sukses atau dispatch manual |
| Job | Tujuan | Kapan berjalan |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Mendeteksi perubahan khusus docs, cakupan yang berubah, extension yang berubah, dan membangun manifest CI | Selalu pada push dan PR non-draft |
| `security-scm-fast` | Deteksi private key dan audit workflow melalui `zizmor` | Selalu pada push dan PR non-draft |
| `security-dependency-audit` | Audit lockfile produksi bebas dependensi terhadap advisory npm | Selalu pada push dan PR non-draft |
| `security-fast` | Agregat wajib untuk job keamanan cepat | Selalu pada push dan PR non-draft |
| `check-dependencies` | Pass khusus dependensi Knip produksi plus guard allowlist file yang tidak digunakan | Perubahan yang relevan dengan Node |
| `build-artifacts` | Membangun `dist/`, Control UI, pemeriksaan artefak hasil build, dan artefak downstream yang dapat digunakan ulang | Perubahan yang relevan dengan Node |
| `checks-fast-core` | Lane kebenaran Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan yang relevan dengan Node |
| `checks-fast-contracts-channels` | Pemeriksaan kontrak channel yang di-shard dengan hasil pemeriksaan agregat stabil | Perubahan yang relevan dengan Node |
| `checks-node-core-test` | Shard pengujian Core Node, mengecualikan lane channel, bundled, contract, dan extension | Perubahan yang relevan dengan Node |
| `check` | Ekuivalen gate lokal utama yang di-shard: tipe prod, lint, guard, tipe pengujian, dan smoke ketat | Perubahan yang relevan dengan Node |
| `check-additional` | Shard arsitektur, boundary, guard permukaan extension, package-boundary, dan gateway-watch | Perubahan yang relevan dengan Node |
| `build-smoke` | Pengujian smoke built-CLI dan smoke memori startup | Perubahan yang relevan dengan Node |
| `checks` | Verifier untuk pengujian channel artefak hasil build | Perubahan yang relevan dengan Node |
| `checks-node-compat-node22` | Lane build dan smoke kompatibilitas Node 22 | Dispatch CI manual untuk rilis |
| `check-docs` | Pemformatan docs, lint, dan pemeriksaan link rusak | Docs berubah |
| `skills-python` | Ruff + pytest untuk skills berbasis Python | Perubahan yang relevan dengan skill Python |
| `checks-windows` | Pengujian proses/path khusus Windows plus regresi specifier impor runtime bersama | Perubahan yang relevan dengan Windows |
| `macos-node` | Lane pengujian TypeScript macOS menggunakan artefak hasil build bersama | Perubahan yang relevan dengan macOS |
| `macos-swift` | Swift lint, build, dan pengujian untuk aplikasi macOS | Perubahan yang relevan dengan macOS |
| `android` | Pengujian unit Android untuk kedua flavor plus satu build APK debug | Perubahan yang relevan dengan Android |
| `test-performance-agent` | Optimisasi pengujian lambat Codex harian setelah aktivitas tepercaya | CI main berhasil atau dispatch manual |
## Urutan fail-fast
1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah langkah di dalam job ini, bukan job mandiri.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal dengan cepat tanpa menunggu job artefak dan matriks platform yang lebih berat.
3. `build-artifacts` tumpang tindih dengan lane Linux cepat sehingga konsumen downstream dapat mulai segera setelah build bersama siap.
1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah langkah di dalam job ini, bukan job tersendiri.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal cepat tanpa menunggu job artefak dan matriks platform yang lebih berat.
3. `build-artifacts` berjalan tumpang tindih dengan lane Linux cepat sehingga konsumen downstream dapat mulai segera setelah build bersama siap.
4. Lane platform dan runtime yang lebih berat menyebar setelah itu: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, dan `android`.
GitHub dapat menandai job yang tergantikan sebagai `cancelled` ketika push yang lebih baru masuk ke PR atau ref `main` yang sama. Anggap itu sebagai noise CI kecuali run terbaru untuk ref yang sama juga gagal. Pemeriksaan shard agregat menggunakan `!cancelled() && always()` sehingga tetap melaporkan kegagalan shard normal tetapi tidak mengantre setelah seluruh workflow sudah tergantikan. Kunci konkurensi CI otomatis diberi versi (`CI-v7-*`) sehingga zombie sisi GitHub dalam grup antrean lama tidak dapat memblokir run main yang lebih baru tanpa batas. Run full-suite manual menggunakan `CI-manual-v1-*` dan tidak membatalkan run yang sedang berjalan.
GitHub dapat menandai job yang tergantikan sebagai `cancelled` ketika push yang lebih baru masuk ke PR yang sama atau ref `main`. Perlakukan itu sebagai noise CI kecuali run terbaru untuk ref yang sama juga gagal. Pemeriksaan shard agregat menggunakan `!cancelled() && always()` sehingga tetap melaporkan kegagalan shard normal tetapi tidak mengantre setelah seluruh workflow sudah tergantikan. Kunci concurrency CI otomatis diberi versi (`CI-v7-*`) sehingga zombie sisi GitHub dalam grup antrean lama tidak dapat memblokir run main yang lebih baru tanpa batas. Run full-suite manual menggunakan `CI-manual-v1-*` dan tidak membatalkan run yang sedang berjalan.
## Scope dan routing
## Cakupan dan routing
Logika scope berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh pengujian unit di `src/scripts/ci-changed-scope.test.ts`. Dispatch manual melewati deteksi changed-scope dan membuat manifes preflight bertindak seolah setiap area berscope berubah.
Logika cakupan berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh pengujian unit di `src/scripts/ci-changed-scope.test.ts`. Dispatch manual melewati deteksi changed-scope dan membuat manifest preflight bertindak seolah setiap area bercakupan berubah.
- **Edit workflow CI** memvalidasi grafik CI Node ditambah linting workflow, tetapi tidak memaksa build native Windows, Android, atau macOS dengan sendirinya; lane platform tersebut tetap terscope pada perubahan sumber platform.
- **Edit khusus routing CI, edit fixture core-test murah tertentu, dan edit helper/test-routing kontrak Plugin yang sempit** menggunakan jalur manifes cepat khusus Node: `preflight`, keamanan, dan satu tugas `checks-fast-core`. Jalur itu melewati artefak build, kompatibilitas Node 22, kontrak channel, shard core penuh, shard bundled-plugin, dan matriks guard tambahan ketika perubahan terbatas pada permukaan routing atau helper yang diuji langsung oleh tugas cepat.
- **Pemeriksaan Node Windows** terscope pada wrapper proses/path khusus Windows, helper runner npm/pnpm/UI, konfigurasi package manager, dan permukaan workflow CI yang mengeksekusi lane tersebut; perubahan sumber, Plugin, install-smoke, dan khusus pengujian yang tidak terkait tetap berada di lane Linux Node.
- **Edit workflow CI** memvalidasi graph CI Node plus linting workflow, tetapi tidak memaksa build native Windows, Android, atau macOS dengan sendirinya; lane platform tersebut tetap dicakup ke perubahan source platform.
- **Edit khusus routing CI, edit fixture core-test murah tertentu, dan edit helper/test-routing kontrak plugin yang sempit** menggunakan path manifest cepat khusus Node: `preflight`, keamanan, dan satu task `checks-fast-core`. Path tersebut melewati artefak build, kompatibilitas Node 22, kontrak channel, shard core penuh, shard bundled-plugin, dan matriks guard tambahan ketika perubahan terbatas pada permukaan routing atau helper yang langsung diuji task cepat.
- **Pemeriksaan Windows Node** dicakup ke wrapper proses/path khusus Windows, helper runner npm/pnpm/UI, konfigurasi package manager, dan permukaan workflow CI yang mengeksekusi lane tersebut; perubahan source, plugin, install-smoke, dan khusus pengujian yang tidak terkait tetap berada pada lane Linux Node.
Keluarga pengujian Node paling lambat dipecah atau diseimbangkan agar setiap job tetap kecil tanpa memesan runner berlebihan: kontrak channel berjalan sebagai tiga shard berbobot, lane unit core kecil dipasangkan, auto-reply berjalan sebagai empat worker seimbang (dengan subtree reply dipecah menjadi shard agent-runner, dispatch, dan commands/state-routing), dan konfigurasi agentic gateway/plugin disebar di seluruh job Node agentic khusus sumber yang ada alih-alih menunggu artefak build. Pengujian browser, QA, media, dan Plugin lain-lain yang luas menggunakan konfigurasi Vitest khususnya alih-alih catch-all Plugin bersama. Shard include-pattern merekam entri timing menggunakan nama shard CI, sehingga `.artifacts/vitest-shard-timings.json` dapat membedakan seluruh konfigurasi dari shard terfilter. `check-additional` menjaga pekerjaan compile/canary package-boundary tetap bersama dan memisahkan arsitektur topologi runtime dari cakupan gateway watch; shard guard boundary menjalankan guard independen kecilnya secara konkuren di dalam satu job. Gateway watch, pengujian channel, dan shard core support-boundary berjalan secara konkuren di dalam `build-artifacts` setelah `dist/` dan `dist-runtime/` sudah dibuild.
Keluarga pengujian Node paling lambat dibagi atau diseimbangkan agar setiap job tetap kecil tanpa memesan runner berlebihan: kontrak channel berjalan sebagai tiga shard berbobot, lane unit core kecil dipasangkan, auto-reply berjalan sebagai empat worker seimbang (dengan subtree reply dibagi menjadi shard agent-runner, dispatch, dan commands/state-routing), dan konfigurasi agentic gateway/plugin disebar ke seluruh job agentic Node source-only yang ada alih-alih menunggu artefak hasil build. Pengujian plugin browser luas, QA, media, dan miscellaneous menggunakan konfigurasi Vitest khusus masing-masing alih-alih catch-all plugin bersama. Shard include-pattern mencatat entri timing menggunakan nama shard CI, sehingga `.artifacts/vitest-shard-timings.json` dapat membedakan seluruh config dari shard terfilter. `check-additional` menjaga pekerjaan compile/canary package-boundary tetap bersama dan memisahkan arsitektur topologi runtime dari cakupan gateway watch; shard guard boundary menjalankan guard independen kecilnya secara konkuren dalam satu job. Gateway watch, pengujian channel, dan shard support-boundary core berjalan secara konkuren di dalam `build-artifacts` setelah `dist/` dan `dist-runtime/` sudah dibangun.
CI Android menjalankan `testPlayDebugUnitTest` dan `testThirdPartyDebugUnitTest`, lalu membuild APK debug Play. Flavor pihak ketiga tidak memiliki source set atau manifes terpisah; lane pengujian unitnya tetap mengompilasi flavor dengan flag BuildConfig SMS/call-log, sambil menghindari job packaging APK debug duplikat pada setiap push yang relevan dengan Android.
CI Android menjalankan `testPlayDebugUnitTest` dan `testThirdPartyDebugUnitTest` lalu membangun APK debug Play. Flavor third-party tidak memiliki source set atau manifest terpisah; lane pengujian unitnya tetap mengompilasi flavor dengan flag BuildConfig SMS/call-log, sambil menghindari job packaging APK debug duplikat pada setiap push yang relevan dengan Android.
Shard `check-dependencies` menjalankan `pnpm deadcode:dependencies` (pass khusus dependensi Knip produksi yang dipin ke versi Knip terbaru, dengan usia rilis minimum pnpm dinonaktifkan untuk instalasi `dlx`) dan `pnpm deadcode:unused-files`, yang membandingkan temuan file produksi tidak terpakai dari Knip terhadap `scripts/deadcode-unused-files.allowlist.mjs`. Guard file tidak terpakai gagal ketika PR menambahkan file tidak terpakai baru yang belum ditinjau atau meninggalkan entri allowlist usang, sambil mempertahankan permukaan Plugin dinamis yang disengaja, generated, build, live-test, dan package bridge yang tidak dapat diselesaikan Knip secara statis.
Shard `check-dependencies` menjalankan `pnpm deadcode:dependencies` (pass khusus dependensi Knip produksi yang dipin ke versi Knip terbaru, dengan usia rilis minimum pnpm dinonaktifkan untuk instalasi `dlx`) dan `pnpm deadcode:unused-files`, yang membandingkan temuan file produksi tidak digunakan dari Knip dengan `scripts/deadcode-unused-files.allowlist.mjs`. Guard file tidak digunakan gagal ketika PR menambahkan file tidak digunakan baru yang belum ditinjau atau meninggalkan entri allowlist usang, sambil mempertahankan permukaan plugin dinamis, generated, build, live-test, dan bridge package yang disengaja yang tidak dapat diselesaikan Knip secara statis.
## Dispatch manual
Dispatch CI manual menjalankan grafik job yang sama seperti CI normal tetapi memaksa setiap lane berscope non-Android aktif: shard Linux Node, shard bundled-plugin, kontrak channel, kompatibilitas Node 22, `check`, `check-additional`, build smoke, pemeriksaan docs, skill Python, Windows, macOS, dan i18n Control UI. Dispatch CI manual mandiri menjalankan Android hanya dengan `include_android=true`; payung rilis penuh mengaktifkan Android dengan meneruskan `include_android=true`. Pemeriksaan statis prerelease Plugin, shard `agentic-plugins` khusus rilis, sweep batch extension penuh, dan lane Docker prerelease Plugin dikecualikan dari CI. Suite Docker prerelease berjalan hanya ketika `Full Release Validation` mendispatch workflow `Plugin Prerelease` terpisah dengan gate release-validation diaktifkan.
Dispatch CI manual menjalankan graph job yang sama seperti CI normal tetapi memaksa setiap lane bercakupan non-Android aktif: shard Linux Node, shard bundled-plugin, kontrak channel, kompatibilitas Node 22, `check`, `check-additional`, build smoke, pemeriksaan docs, Python skills, Windows, macOS, dan i18n Control UI. Dispatch CI manual mandiri menjalankan Android hanya dengan `include_android=true`; payung rilis penuh mengaktifkan Android dengan meneruskan `include_android=true`. Pemeriksaan statis prerelease plugin, shard `agentic-plugins` khusus rilis, sweep batch extension penuh, dan lane Docker prerelease plugin dikecualikan dari CI. Suite Docker prerelease berjalan hanya ketika `Full Release Validation` men-dispatch workflow `Plugin Prerelease` terpisah dengan gate release-validation diaktifkan.
Run manual menggunakan grup konkurensi unik sehingga suite penuh kandidat rilis tidak dibatalkan oleh push atau run PR lain pada ref yang sama. Input opsional `target_ref` memungkinkan pemanggil tepercaya menjalankan grafik itu terhadap branch, tag, atau SHA commit lengkap sambil menggunakan file workflow dari ref dispatch yang dipilih.
Run manual menggunakan grup concurrency unik sehingga full suite kandidat rilis tidak dibatalkan oleh push atau run PR lain pada ref yang sama. Input opsional `target_ref` memungkinkan pemanggil tepercaya menjalankan graph tersebut terhadap branch, tag, atau full commit SHA sambil menggunakan file workflow dari ref dispatch yang dipilih.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -79,15 +79,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Runner
| Runner | Pekerjaan |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, pekerjaan keamanan cepat dan agregat (`security-scm-fast`, `security-dependency-audit`, `security-fast`), pemeriksaan cepat protokol/kontrak/bundel, pemeriksaan kontrak channel yang di-shard, shard `check` kecuali lint, shard dan agregat `check-additional`, pemverifikasi agregat pengujian Node, pemeriksaan docs, Python skills, workflow-sanity, labeler, auto-response; preflight install-smoke juga memakai Ubuntu yang di-host GitHub agar matriks Blacksmith dapat mengantre lebih awal |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shard Plugin berbobot lebih rendah, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types`, dan `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard pengujian Node Linux, shard pengujian Plugin bundel, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (cukup sensitif CPU sehingga 8 vCPU biayanya lebih besar daripada penghematannya); build Docker install-smoke (biaya waktu antrean 32-vCPU lebih besar daripada penghematannya) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` di `openclaw/openclaw`; fork fallback ke `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` di `openclaw/openclaw`; fork fallback ke `macos-latest` |
| Pelaksana | Pekerjaan |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, pekerjaan keamanan cepat dan agregat (`security-scm-fast`, `security-dependency-audit`, `security-fast`), pemeriksaan protokol/kontrak/terbundel cepat, pemeriksaan kontrak kanal yang dipecah shard, shard `check` kecuali lint, shard dan agregat `check-additional`, pemverifikasi agregat pengujian Node, pemeriksaan dokumentasi, Python skills, workflow-sanity, labeler, auto-response; preflight install-smoke juga memakai Ubuntu yang di-host GitHub agar matriks Blacksmith dapat mengantre lebih awal |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shard plugin berbobot lebih rendah, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types`, dan `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard pengujian Node Linux, shard pengujian Plugin terbundel, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (cukup sensitif terhadap CPU sehingga 8 vCPU lebih mahal daripada penghematan yang diberikan); build Docker install-smoke (waktu antrean 32-vCPU lebih mahal daripada penghematan yang diberikan) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` pada `openclaw/openclaw`; fork kembali memakai `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` pada `openclaw/openclaw`; fork kembali memakai `macos-latest` |
## Padanan lokal
@ -115,29 +115,29 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
```
## Validasi Rilis Penuh
## Validasi Rilis Lengkap
`Full Release Validation` adalah alur kerja payung manual untuk "menjalankan semuanya sebelum rilis." Alur ini menerima branch, tag, atau SHA commit lengkap, men-dispatch alur kerja manual `CI` dengan target tersebut, men-dispatch `Plugin Prerelease` untuk pembuktian khusus rilis bagi Plugin/package/static/Docker, dan men-dispatch `OpenClaw Release Checks` untuk install smoke, package acceptance, suite jalur rilis Docker, live/E2E, OpenWebUI, paritas QA Lab, Matrix, dan lane Telegram. Alur ini juga dapat menjalankan alur kerja pascapublikasi `NPM Telegram Beta E2E` ketika spesifikasi package yang sudah dipublikasikan diberikan.
`Full Release Validation` adalah alur kerja payung manual untuk "menjalankan semuanya sebelum rilis." Ini menerima branch, tag, atau SHA commit lengkap, memicu alur kerja `CI` manual dengan target tersebut, memicu `Plugin Prerelease` untuk bukti Plugin/paket/statis/Docker khusus rilis, dan memicu `OpenClaw Release Checks` untuk smoke instalasi, penerimaan paket, rangkaian jalur rilis Docker, live/E2E, OpenWebUI, paritas QA Lab, Matrix, dan lane Telegram. Ini juga dapat menjalankan alur kerja pascapublikasi `NPM Telegram Beta E2E` ketika spesifikasi paket yang telah dipublikasikan disediakan.
`release_profile` mengontrol keluasan live/provider yang diteruskan ke pemeriksaan rilis:
`release_profile` mengendalikan cakupan live/penyedia yang diteruskan ke pemeriksaan rilis:
- `minimum` mempertahankan lane OpenAI/core tercepat yang kritis untuk rilis.
- `stable` menambahkan set provider/backend stabil.
- `full` menjalankan matriks provider/media advisory yang luas.
- `stable` menambahkan kumpulan penyedia/backend stabil.
- `full` menjalankan matriks penyedia/media advisory yang luas.
Payung mencatat id run child yang di-dispatch, dan pekerjaan akhir `Verify full validation` memeriksa ulang conclusion run child saat ini dan menambahkan tabel pekerjaan terlambat untuk setiap run child. Jika alur kerja child dijalankan ulang dan menjadi hijau, jalankan ulang hanya pekerjaan verifier induk untuk menyegarkan hasil payung dan ringkasan waktu.
Payung mencatat id run turunan yang dipicu, dan pekerjaan akhir `Verify full validation` memeriksa ulang kesimpulan run turunan saat ini serta menambahkan tabel pekerjaan terlambat untuk setiap run turunan. Jika sebuah alur kerja turunan dijalankan ulang dan menjadi hijau, jalankan ulang hanya pekerjaan pemverifikasi induk untuk menyegarkan hasil payung dan ringkasan waktunya.
Untuk pemulihan, `Full Release Validation` dan `OpenClaw Release Checks` menerima `rerun_group`. Gunakan `all` untuk kandidat rilis, `ci` hanya untuk child CI penuh normal, `release-checks` untuk setiap child rilis, atau grup yang lebih sempit: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, atau `npm-telegram` pada payung. Ini menjaga rerun kotak rilis yang gagal tetap terbatas setelah perbaikan terfokus.
Untuk pemulihan, baik `Full Release Validation` maupun `OpenClaw Release Checks` menerima `rerun_group`. Gunakan `all` untuk kandidat rilis, `ci` hanya untuk turunan CI penuh normal, `release-checks` untuk setiap turunan rilis, atau grup yang lebih sempit: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, atau `npm-telegram` pada payung. Ini menjaga agar run ulang kotak rilis yang gagal tetap terbatas setelah perbaikan terfokus.
`OpenClaw Release Checks` memakai ref alur kerja tepercaya untuk me-resolve ref yang dipilih sekali menjadi tarball `release-package-under-test`, lalu meneruskan artefak itu ke alur kerja Docker live/E2E jalur rilis dan shard package acceptance. Ini menjaga byte package tetap konsisten di seluruh kotak rilis dan menghindari pemaketan ulang kandidat yang sama di beberapa pekerjaan child.
`OpenClaw Release Checks` memakai ref alur kerja tepercaya untuk menyelesaikan ref yang dipilih sekali menjadi tarball `release-package-under-test`, lalu meneruskan artefak itu ke alur kerja Docker jalur rilis live/E2E dan shard penerimaan paket. Ini menjaga byte paket tetap konsisten di seluruh kotak rilis dan menghindari pengemasan ulang kandidat yang sama di beberapa pekerjaan turunan.
## Shard live dan E2E
Child live/E2E rilis mempertahankan cakupan luas `pnpm test:live` native, tetapi menjalankannya sebagai shard bernama melalui `scripts/test-live-shard.mjs`, bukan satu pekerjaan serial:
Turunan live/E2E rilis mempertahankan cakupan `pnpm test:live` native yang luas, tetapi menjalankannya sebagai shard bernama melalui `scripts/test-live-shard.mjs` alih-alih satu pekerjaan serial:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- pekerjaan `native-live-src-gateway-profiles` yang difilter provider
- pekerjaan `native-live-src-gateway-profiles` yang difilter penyedia
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -145,57 +145,57 @@ Child live/E2E rilis mempertahankan cakupan luas `pnpm test:live` native, tetapi
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- shard media audio/video terpisah dan shard musik yang difilter provider
- shard media audio/video terpisah dan shard musik yang difilter penyedia
Ini mempertahankan cakupan file yang sama sekaligus membuat kegagalan provider live yang lambat lebih mudah dijalankan ulang dan didiagnosis. Nama shard agregat `native-live-extensions-o-z`, `native-live-extensions-media`, dan `native-live-extensions-media-music` tetap valid untuk rerun sekali jalan manual.
Ini mempertahankan cakupan file yang sama sambil membuat kegagalan penyedia live yang lambat lebih mudah dijalankan ulang dan didiagnosis. Nama shard agregat `native-live-extensions-o-z`, `native-live-extensions-media`, dan `native-live-extensions-media-music` tetap valid untuk run ulang manual sekali jalan.
Shard media live native berjalan di `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, yang dibangun oleh alur kerja `Live Media Runner Image`. Image tersebut sudah memasang `ffmpeg` dan `ffprobe`; pekerjaan media hanya memverifikasi binary sebelum setup. Pertahankan suite live berbasis Docker pada runner Blacksmith normal — pekerjaan container bukan tempat yang tepat untuk meluncurkan pengujian Docker bersarang.
Shard media live native berjalan di `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, yang dibuat oleh alur kerja `Live Media Runner Image`. Image itu memasang `ffmpeg` dan `ffprobe` sebelumnya; pekerjaan media hanya memverifikasi biner sebelum penyiapan. Pertahankan rangkaian live berbasis Docker pada runner Blacksmith normal — pekerjaan kontainer bukan tempat yang tepat untuk meluncurkan pengujian Docker bersarang.
Shard model/backend live berbasis Docker memakai image bersama terpisah `ghcr.io/openclaw/openclaw-live-test:<sha>` per commit yang dipilih. Alur kerja rilis live membangun dan mendorong image tersebut sekali, lalu shard model live Docker, Gateway, backend CLI, bind ACP, dan harness Codex berjalan dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`. Jika shard tersebut membangun ulang target Docker sumber lengkap secara independen, run rilis salah konfigurasi dan akan membuang waktu berjalan untuk build image duplikat.
Shard model/backend live berbasis Docker memakai image bersama terpisah `ghcr.io/openclaw/openclaw-live-test:<sha>` per commit yang dipilih. Alur kerja rilis live membuat dan mendorong image itu sekali, lalu shard model live Docker, Gateway, backend CLI, bind ACP, dan harness Codex berjalan dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`. Jika shard tersebut membangun ulang target Docker sumber penuh secara independen, run rilis salah dikonfigurasi dan akan membuang waktu dinding untuk build image duplikat.
## Package Acceptance
## Penerimaan Paket
Gunakan `Package Acceptance` ketika pertanyaannya adalah "apakah package OpenClaw yang dapat diinstal ini berfungsi sebagai produk?" Ini berbeda dari CI normal: CI normal memvalidasi pohon sumber, sedangkan package acceptance memvalidasi satu tarball melalui harness Docker E2E yang sama yang digunakan pengguna setelah instalasi atau pembaruan.
Gunakan `Package Acceptance` ketika pertanyaannya adalah "apakah paket OpenClaw yang dapat diinstal ini berfungsi sebagai produk?" Ini berbeda dari CI normal: CI normal memvalidasi pohon sumber, sedangkan penerimaan paket memvalidasi satu tarball melalui harness Docker E2E yang sama yang digunakan pengguna setelah instalasi atau pembaruan.
### Pekerjaan
1. `resolve_package` melakukan checkout `workflow_ref`, me-resolve satu kandidat package, menulis `.artifacts/docker-e2e-package/openclaw-current.tgz`, menulis `.artifacts/docker-e2e-package/package-candidate.json`, mengunggah keduanya sebagai artefak `package-under-test`, dan mencetak sumber, ref alur kerja, ref package, versi, SHA-256, dan profil dalam ringkasan langkah GitHub.
2. `docker_acceptance` memanggil `openclaw-live-and-e2e-checks-reusable.yml` dengan `ref=workflow_ref` dan `package_artifact_name=package-under-test`. Alur kerja reusable mengunduh artefak itu, memvalidasi inventaris tarball, menyiapkan image Docker package-digest bila diperlukan, dan menjalankan lane Docker yang dipilih terhadap package tersebut alih-alih memaketkan checkout alur kerja. Ketika suatu profil memilih beberapa `docker_lanes` bertarget, alur kerja reusable menyiapkan package dan image bersama sekali, lalu menyebarkan lane tersebut sebagai pekerjaan Docker bertarget paralel dengan artefak unik.
3. `package_telegram` secara opsional memanggil `NPM Telegram Beta E2E`. Ini berjalan ketika `telegram_mode` bukan `none` dan memasang artefak `package-under-test` yang sama ketika Package Acceptance me-resolve satu; dispatch Telegram mandiri tetap dapat memasang spesifikasi npm yang telah dipublikasikan.
4. `summary` menggagalkan alur kerja jika resolusi package, Docker acceptance, atau lane Telegram opsional gagal.
1. `resolve_package` melakukan checkout `workflow_ref`, menyelesaikan satu kandidat paket, menulis `.artifacts/docker-e2e-package/openclaw-current.tgz`, menulis `.artifacts/docker-e2e-package/package-candidate.json`, mengunggah keduanya sebagai artefak `package-under-test`, dan mencetak sumber, ref alur kerja, ref paket, versi, SHA-256, dan profil dalam ringkasan langkah GitHub.
2. `docker_acceptance` memanggil `openclaw-live-and-e2e-checks-reusable.yml` dengan `ref=workflow_ref` dan `package_artifact_name=package-under-test`. Alur kerja yang dapat digunakan ulang mengunduh artefak itu, memvalidasi inventaris tarball, menyiapkan image Docker digest paket saat diperlukan, dan menjalankan lane Docker yang dipilih terhadap paket itu alih-alih mengemas checkout alur kerja. Ketika sebuah profil memilih beberapa `docker_lanes` tertarget, alur kerja yang dapat digunakan ulang menyiapkan paket dan image bersama sekali, lalu menyebarkan lane tersebut sebagai pekerjaan Docker tertarget paralel dengan artefak unik.
3. `package_telegram` secara opsional memanggil `NPM Telegram Beta E2E`. Ini berjalan ketika `telegram_mode` bukan `none` dan memasang artefak `package-under-test` yang sama ketika Package Acceptance menyelesaikan satu paket; dispatch Telegram mandiri masih dapat memasang spesifikasi npm yang dipublikasikan.
4. `summary` menggagalkan alur kerja jika resolusi paket, penerimaan Docker, atau lane Telegram opsional gagal.
### Sumber kandidat
- `source=npm` hanya menerima `openclaw@beta`, `openclaw@latest`, atau versi rilis OpenClaw yang persis seperti `openclaw@2026.4.27-beta.2`. Gunakan ini untuk penerimaan beta/stabil yang telah dipublikasikan.
- `source=ref` mengemas cabang, tag, atau SHA commit penuh `package_ref` tepercaya. Resolver mengambil cabang/tag OpenClaw, memverifikasi bahwa commit yang dipilih dapat dijangkau dari riwayat cabang repositori atau tag rilis, menginstal dependensi di worktree terpisah, dan mengemasnya dengan `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` hanya menerima `openclaw@beta`, `openclaw@latest`, atau versi rilis OpenClaw yang persis seperti `openclaw@2026.4.27-beta.2`. Gunakan ini untuk penerimaan beta/stabil yang dipublikasikan.
- `source=ref` mengemas branch, tag, atau SHA commit lengkap `package_ref` yang tepercaya. Resolver mengambil branch/tag OpenClaw, memverifikasi commit yang dipilih dapat dijangkau dari riwayat branch repositori atau tag rilis, menginstal dependensi di worktree terlepas, dan mengemasnya dengan `scripts/package-openclaw-for-docker.mjs`.
- `source=url` mengunduh `.tgz` HTTPS; `package_sha256` wajib.
- `source=artifact` mengunduh satu `.tgz` dari `artifact_run_id` dan `artifact_name`; `package_sha256` opsional tetapi sebaiknya disediakan untuk artefak yang dibagikan secara eksternal.
- `source=artifact` mengunduh satu `.tgz` dari `artifact_run_id` dan `artifact_name`; `package_sha256` opsional tetapi sebaiknya disediakan untuk artifact yang dibagikan secara eksternal.
Pisahkan `workflow_ref` dan `package_ref`. `workflow_ref` adalah kode workflow/harness tepercaya yang menjalankan pengujian. `package_ref` adalah commit sumber yang dikemas ketika `source=ref`. Ini memungkinkan harness pengujian saat ini memvalidasi commit sumber tepercaya yang lebih lama tanpa menjalankan logika workflow lama.
Pisahkan `workflow_ref` dan `package_ref`. `workflow_ref` adalah kode workflow/harness tepercaya yang menjalankan pengujian. `package_ref` adalah commit sumber yang dikemas saat `source=ref`. Ini memungkinkan harness pengujian saat ini memvalidasi commit sumber tepercaya yang lebih lama tanpa menjalankan logika workflow lama.
### Profil suite
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `product` — `package` ditambah `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — chunk jalur rilis Docker lengkap dengan OpenWebUI
- `custom` — `docker_lanes` persis; wajib ketika `suite_profile=custom`
- `full` — chunk jalur rilis Docker penuh dengan OpenWebUI
- `custom` — `docker_lanes` persis; wajib saat `suite_profile=custom`
Profil `package` menggunakan cakupan Plugin offline sehingga validasi paket yang dipublikasikan tidak bergantung pada ketersediaan ClawHub live. Lane Telegram opsional menggunakan kembali artefak `package-under-test` di `NPM Telegram Beta E2E`, dengan jalur spesifikasi npm yang dipublikasikan tetap tersedia untuk dispatch mandiri.
Profil `package` menggunakan cakupan Plugin offline sehingga validasi paket yang dipublikasikan tidak bergantung pada ketersediaan ClawHub live. Lane Telegram opsional menggunakan kembali artifact `package-under-test` di `NPM Telegram Beta E2E`, dengan jalur spesifikasi npm yang dipublikasikan tetap dipertahankan untuk dispatch mandiri.
Pemeriksaan rilis memanggil Package Acceptance dengan `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'`, dan `telegram_mode=mock-openai`. Chunk Docker jalur rilis mencakup lane paket/update/Plugin yang tumpang tindih; Package Acceptance mempertahankan bukti kompatibilitas bundled-channel native artefak, Plugin offline, dan Telegram terhadap tarball paket terselesaikan yang sama. Pemeriksaan rilis lintas OS tetap mencakup onboarding, installer, dan perilaku platform spesifik OS; validasi produk paket/update harus dimulai dengan Package Acceptance. Lane paket Windows dan installer fresh juga memverifikasi bahwa paket yang terinstal dapat mengimpor override browser-control dari jalur Windows absolut mentah. Smoke agent-turn lintas OS OpenAI memakai default `OPENCLAW_CROSS_OS_OPENAI_MODEL` ketika disetel, jika tidak `openai/gpt-5.4-mini`, sehingga bukti instalasi dan Gateway tetap cepat dan deterministik.
Pemeriksaan rilis memanggil Package Acceptance dengan `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'`, dan `telegram_mode=mock-openai`. Chunk Docker jalur rilis mencakup lane paket/pembaruan/Plugin yang tumpang tindih; Package Acceptance mempertahankan bukti kompatibilitas bundled-channel native artifact, Plugin offline, dan Telegram terhadap tarball paket terselesaikan yang sama. Pemeriksaan rilis lintas OS tetap mencakup onboarding, penginstal, dan perilaku platform yang spesifik OS; validasi produk paket/pembaruan harus dimulai dengan Package Acceptance. Lane paket Windows dan fresh penginstal juga memverifikasi bahwa paket terinstal dapat mengimpor override kontrol browser dari path Windows absolut mentah. Smoke agent-turn lintas OS OpenAI menggunakan default `OPENCLAW_CROSS_OS_OPENAI_MODEL` saat disetel, jika tidak `openai/gpt-5.4-mini`, sehingga bukti install dan Gateway tetap cepat dan deterministik.
### Jendela kompatibilitas lama
### Jendela kompatibilitas warisan
Package Acceptance memiliki jendela kompatibilitas lama terbatas untuk paket yang sudah dipublikasikan. Paket hingga `2026.4.25`, termasuk `2026.4.25-beta.*`, dapat menggunakan jalur kompatibilitas:
Package Acceptance memiliki jendela kompatibilitas warisan terbatas untuk paket yang sudah dipublikasikan. Paket hingga `2026.4.25`, termasuk `2026.4.25-beta.*`, dapat menggunakan jalur kompatibilitas:
- entri QA privat yang dikenal di `dist/postinstall-inventory.json` dapat menunjuk ke file yang dihilangkan dari tarball;
- `doctor-switch` dapat melewati subkasus persistensi `gateway install --wrapper` ketika paket tidak mengekspos flag tersebut;
- `update-channel-switch` dapat memangkas `pnpm.patchedDependencies` yang hilang dari fixture git palsu turunan tarball dan dapat mencatat `update.channel` yang dipersistenkan hilang;
- smoke Plugin dapat membaca lokasi install-record lama atau menerima persistensi install-record marketplace yang hilang;
- `plugin-update` dapat mengizinkan migrasi metadata konfigurasi sambil tetap mewajibkan install record dan perilaku tanpa reinstall tetap tidak berubah.
- `doctor-switch` dapat melewati subkasus persistensi `gateway install --wrapper` saat paket tidak mengekspos flag tersebut;
- `update-channel-switch` dapat memangkas `pnpm.patchedDependencies` yang hilang dari fixture git palsu turunan tarball dan dapat mencatat `update.channel` tersimpan yang hilang;
- smoke Plugin dapat membaca lokasi catatan install warisan atau menerima persistensi catatan install marketplace yang hilang;
- `plugin-update` dapat mengizinkan migrasi metadata konfigurasi sambil tetap mewajibkan catatan install dan perilaku tanpa reinstall tetap tidak berubah.
Paket `2026.4.26` yang dipublikasikan juga dapat memberi peringatan untuk file cap metadata build lokal yang sudah dikirimkan. Paket berikutnya harus memenuhi kontrak modern; kondisi yang sama akan gagal, bukan memberi peringatan atau dilewati.
Paket `2026.4.26` yang dipublikasikan juga dapat memberi peringatan untuk file stempel metadata build lokal yang sudah dikirimkan. Paket yang lebih baru harus memenuhi kontrak modern; kondisi yang sama akan gagal, bukan memperingatkan atau melewati.
### Contoh
@ -238,111 +238,111 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Saat men-debug run package acceptance yang gagal, mulai dari ringkasan `resolve_package` untuk mengonfirmasi sumber paket, versi, dan SHA-256. Lalu periksa run anak `docker_acceptance` dan artefak Docker-nya: `.artifacts/docker-tests/**/summary.json`, `failures.json`, log lane, timing fase, dan perintah rerun. Lebih baik menjalankan ulang profil paket yang gagal atau lane Docker persis daripada menjalankan ulang validasi rilis penuh.
Saat men-debug run penerimaan paket yang gagal, mulai dari ringkasan `resolve_package` untuk mengonfirmasi sumber paket, versi, dan SHA-256. Lalu periksa child run `docker_acceptance` dan artifact Docker-nya: `.artifacts/docker-tests/**/summary.json`, `failures.json`, log lane, timing fase, dan perintah rerun. Lebih baik menjalankan ulang profil paket yang gagal atau lane Docker yang persis daripada menjalankan ulang validasi rilis penuh.
## Smoke instalasi
## Smoke install
Workflow `Install Smoke` terpisah menggunakan kembali skrip scope yang sama melalui job `preflight` miliknya sendiri. Workflow ini membagi cakupan smoke menjadi `run_fast_install_smoke` dan `run_full_install_smoke`.
Workflow `Install Smoke` yang terpisah menggunakan kembali skrip cakupan yang sama melalui job `preflight` miliknya. Workflow ini membagi cakupan smoke menjadi `run_fast_install_smoke` dan `run_full_install_smoke`.
- **Jalur cepat** berjalan untuk pull request yang menyentuh permukaan Docker/paket, perubahan paket/manifest Plugin bawaan, atau permukaan inti Plugin/channel/Gateway/Plugin SDK yang diuji oleh job smoke Docker. Perubahan Plugin bawaan khusus sumber, edit khusus pengujian, dan edit khusus docs tidak memesan worker Docker. Jalur cepat membangun image Dockerfile root sekali, memeriksa CLI, menjalankan smoke CLI agents delete shared-workspace, menjalankan e2e container gateway-network, memverifikasi arg build ekstensi bawaan, dan menjalankan profil Docker Plugin bawaan terbatas di bawah timeout perintah agregat 240 detik (setiap run Docker skenario dibatasi secara terpisah).
- **Jalur penuh** mempertahankan instalasi paket QR dan cakupan Docker/update installer untuk run terjadwal nightly, dispatch manual, pemeriksaan rilis workflow-call, dan pull request yang benar-benar menyentuh permukaan installer/paket/Docker. Dalam mode penuh, install-smoke menyiapkan atau menggunakan kembali satu image smoke Dockerfile root GHCR target-SHA, lalu menjalankan instalasi paket QR, smoke Dockerfile/Gateway root, smoke installer/update, dan E2E Docker Plugin bawaan cepat sebagai job terpisah sehingga pekerjaan installer tidak menunggu di belakang smoke image root.
- **Jalur cepat** berjalan untuk pull request yang menyentuh permukaan Docker/paket, perubahan paket/manifest Plugin bawaan, atau permukaan Plugin/channel/Gateway/Plugin SDK inti yang dijalankan oleh job smoke Docker. Perubahan Plugin bawaan khusus sumber, edit khusus pengujian, dan edit khusus docs tidak memesan worker Docker. Jalur cepat membangun image Dockerfile root sekali, memeriksa CLI, menjalankan smoke CLI agents delete shared-workspace, menjalankan e2e container gateway-network, memverifikasi arg build ekstensi bawaan, dan menjalankan profil Docker Plugin bawaan terbatas dengan batas waktu perintah agregat 240 detik (setiap Docker run skenario dibatasi secara terpisah).
- **Jalur penuh** mempertahankan cakupan install paket QR dan Docker/pembaruan penginstal untuk run terjadwal malam, dispatch manual, pemeriksaan rilis workflow-call, dan pull request yang benar-benar menyentuh permukaan penginstal/paket/Docker. Dalam mode penuh, install-smoke menyiapkan atau menggunakan kembali satu image smoke Dockerfile root GHCR target-SHA, lalu menjalankan install paket QR, smoke Dockerfile root/Gateway, smoke penginstal/pembaruan, dan E2E Docker Plugin bawaan cepat sebagai job terpisah agar pekerjaan penginstal tidak menunggu di belakang smoke image root.
Push `main` (termasuk merge commit) tidak memaksa jalur penuh; ketika logika changed-scope meminta cakupan penuh pada push, workflow mempertahankan smoke Docker cepat dan menyerahkan smoke instalasi penuh ke validasi nightly atau rilis.
Push `main` (termasuk merge commit) tidak memaksa jalur penuh; saat logika cakupan perubahan akan meminta cakupan penuh pada push, workflow mempertahankan smoke Docker cepat dan menyerahkan smoke install penuh ke validasi malam atau rilis.
Smoke image-provider instalasi global Bun yang lambat digate secara terpisah oleh `run_bun_global_install_smoke`. Ini berjalan pada jadwal nightly dan dari workflow pemeriksaan rilis, dan dispatch manual `Install Smoke` dapat memilih untuk menyertakannya, tetapi pull request dan push `main` tidak. Pengujian Docker QR dan installer mempertahankan Dockerfile khusus instalasi masing-masing.
Smoke image-provider install global Bun yang lambat digate secara terpisah oleh `run_bun_global_install_smoke`. Ini berjalan pada jadwal malam dan dari workflow pemeriksaan rilis, dan dispatch manual `Install Smoke` dapat ikut mengaktifkannya, tetapi pull request dan push `main` tidak. Pengujian Docker QR dan penginstal mempertahankan Dockerfile berfokus install masing-masing.
## E2E Docker lokal
`pnpm test:docker:all` melakukan prebuild satu image live-test bersama, mengemas OpenClaw sekali sebagai tarball npm, dan membangun dua image `scripts/e2e/Dockerfile` bersama:
- runner Node/Git polos untuk lane installer/update/dependensi-Plugin;
- runner Node/Git polos untuk lane penginstal/pembaruan/dependensi-Plugin;
- image fungsional yang menginstal tarball yang sama ke `/app` untuk lane fungsionalitas normal.
Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`, logika planner berada di `scripts/lib/docker-e2e-plan.mjs`, dan runner hanya mengeksekusi plan yang dipilih. Scheduler memilih image per lane dengan `OPENCLAW_DOCKER_E2E_BARE_IMAGE` dan `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, lalu menjalankan lane dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`.
Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`, logika planner berada di `scripts/lib/docker-e2e-plan.mjs`, dan runner hanya menjalankan plan yang dipilih. Scheduler memilih image per lane dengan `OPENCLAW_DOCKER_E2E_BARE_IMAGE` dan `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, lalu menjalankan lane dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Tuning
### Pengaturan
| Variabel | Default | Tujuan |
| Variabel | Default | Tujuan |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Jumlah slot main-pool untuk lane normal. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Jumlah slot pool utama untuk lane normal. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Jumlah slot tail-pool yang sensitif terhadap provider. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Batas lane live serentak agar provider tidak melakukan throttle. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Batas lane instalasi npm serentak. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Batas lane multi-service serentak. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Jeda bertahap antar-start lane untuk menghindari badai create daemon Docker; setel `0` untuk tanpa jeda bertahap. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout fallback per lane (120 menit); lane live/tail terpilih memakai batas yang lebih ketat. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Batas lane install npm serentak. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Batas lane multi-layanan serentak. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Jeda antar-start lane untuk menghindari lonjakan create daemon Docker; setel `0` untuk tanpa jeda. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout fallback per lane (120 menit); lane live/tail tertentu menggunakan batas lebih ketat. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` mencetak plan scheduler tanpa menjalankan lane. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Daftar lane persis yang dipisahkan koma; melewati cleanup smoke agar agent dapat mereproduksi satu lane yang gagal. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Daftar lane persis yang dipisahkan koma; melewati smoke cleanup agar agent dapat mereproduksi satu lane yang gagal. |
Lane yang lebih berat dari batas efektifnya tetap dapat dimulai dari pool kosong, lalu berjalan sendiri hingga melepas kapasitas. Preflight agregat lokal memeriksa Docker, menghapus container E2E OpenClaw yang usang, menampilkan status lane aktif, mempersistenkan timing lane untuk pengurutan yang terlama lebih dulu, dan secara default berhenti menjadwalkan lane pooled baru setelah kegagalan pertama.
Lane yang lebih berat daripada batas efektifnya tetap dapat dimulai dari pool kosong, lalu berjalan sendiri hingga melepas kapasitas. Agregat lokal melakukan preflight Docker, menghapus container E2E OpenClaw usang, mengeluarkan status lane aktif, menyimpan timing lane untuk pengurutan terlama-terlebih-dahulu, dan secara default berhenti menjadwalkan lane pool baru setelah kegagalan pertama.
### Workflow live/E2E yang dapat digunakan kembali
### Workflow live/E2E yang dapat digunakan ulang
Workflow live/E2E yang dapat digunakan kembali menanyakan `scripts/test-docker-all.mjs --plan-json` tentang paket, jenis image, image live, lane, dan cakupan kredensial yang diperlukan. `scripts/docker-e2e.mjs` lalu mengonversi plan tersebut menjadi output dan ringkasan GitHub. Workflow ini mengemas OpenClaw melalui `scripts/package-openclaw-for-docker.mjs`, mengunduh artefak paket current-run, atau mengunduh artefak paket dari `package_artifact_run_id`; memvalidasi inventaris tarball; membangun dan mendorong image E2E Docker GHCR bare/functional bertag digest paket melalui cache layer Docker Blacksmith ketika plan membutuhkan lane dengan paket terinstal; dan menggunakan kembali input `docker_e2e_bare_image`/`docker_e2e_functional_image` yang disediakan atau image digest paket yang ada alih-alih membangun ulang. Pull image Docker dicoba ulang dengan timeout terbatas 180 detik per percobaan sehingga stream registry/cache yang macet cepat dicoba ulang alih-alih menghabiskan sebagian besar jalur kritis CI.
Workflow live/E2E yang dapat digunakan ulang menanyakan ke `scripts/test-docker-all.mjs --plan-json` paket, jenis image, image live, lane, dan cakupan kredensial apa yang diperlukan. `scripts/docker-e2e.mjs` lalu mengonversi plan tersebut menjadi output dan ringkasan GitHub. Workflow ini mengemas OpenClaw melalui `scripts/package-openclaw-for-docker.mjs`, mengunduh artifact paket run saat ini, atau mengunduh artifact paket dari `package_artifact_run_id`; memvalidasi inventaris tarball; membangun dan mendorong image E2E Docker GHCR bare/fungsional bertag digest paket melalui cache layer Docker Blacksmith saat plan memerlukan lane dengan paket terinstal; dan menggunakan kembali input `docker_e2e_bare_image`/`docker_e2e_functional_image` yang disediakan atau image digest paket yang sudah ada alih-alih membangun ulang. Pull image Docker dicoba ulang dengan timeout terbatas 180 detik per percobaan sehingga stream registry/cache yang macet dicoba ulang dengan cepat alih-alih menghabiskan sebagian besar jalur kritis CI.
### Chunk jalur rilis
Cakupan Docker rilis menjalankan job chunk yang lebih kecil dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` sehingga setiap chunk hanya menarik jenis image yang dibutuhkan dan mengeksekusi beberapa lane melalui scheduler berbobot yang sama:
Cakupan Docker rilis menjalankan job chunk yang lebih kecil dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` sehingga setiap chunk hanya menarik jenis image yang dibutuhkan dan menjalankan beberapa lane melalui scheduler berbobot yang sama:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels`
Chunk Docker rilis saat ini adalah `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` hingga `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b`, dan `bundled-channels-contracts`. Chunk agregat `bundled-channels` tetap tersedia untuk rerun manual sekali jalan, dan `plugins-runtime-core`, `plugins-runtime`, serta `plugins-integrations` tetap menjadi alias Plugin/runtime agregat. Alias lane `install-e2e` tetap menjadi alias rerun manual agregat untuk kedua lane penginstal provider. Chunk `bundled-channels` menjalankan lane `bundled-channel-*` dan `bundled-channel-update-*` yang dipecah, bukan lane `bundled-channel-deps` serial yang serba menjadi satu.
Potongan Docker rilis saat ini adalah `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` hingga `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b`, dan `bundled-channels-contracts`. Potongan agregat `bundled-channels` tetap tersedia untuk pengulangan manual satu kali, dan `plugins-runtime-core`, `plugins-runtime`, serta `plugins-integrations` tetap menjadi alias Plugin/runtime agregat. Alias lane `install-e2e` tetap menjadi alias pengulangan manual agregat untuk kedua lane penginstal penyedia. Potongan `bundled-channels` menjalankan lane `bundled-channel-*` dan `bundled-channel-update-*` yang dipecah, bukan lane serial serba-satu `bundled-channel-deps`.
OpenWebUI digabungkan ke dalam `plugins-runtime-services` saat cakupan jalur rilis penuh memintanya, dan mempertahankan chunk mandiri `openwebui` hanya untuk dispatch khusus OpenWebUI. Lane pembaruan bundled-channel mencoba ulang sekali untuk kegagalan jaringan npm sementara.
OpenWebUI digabungkan ke dalam `plugins-runtime-services` saat cakupan jalur rilis penuh memintanya, dan mempertahankan potongan mandiri `openwebui` hanya untuk dispatch khusus OpenWebUI. Lane pembaruan channel bawaan mencoba ulang sekali untuk kegagalan jaringan npm yang sementara.
Setiap chunk mengunggah `.artifacts/docker-tests/` dengan log lane, timing, `summary.json`, `failures.json`, timing fase, JSON rencana penjadwal, tabel lane lambat, dan perintah rerun per lane. Input alur kerja `docker_lanes` menjalankan lane yang dipilih terhadap image yang disiapkan, bukan job chunk, sehingga debugging lane gagal tetap terbatas pada satu job Docker tertarget dan menyiapkan, mengunduh, atau menggunakan ulang artefak paket untuk run tersebut; jika lane yang dipilih adalah lane Docker live, job tertarget membangun image live-test secara lokal untuk rerun tersebut. Perintah rerun GitHub per lane yang dihasilkan menyertakan `package_artifact_run_id`, `package_artifact_name`, dan input image yang disiapkan saat nilai tersebut ada, sehingga lane yang gagal dapat menggunakan ulang paket dan image persis dari run yang gagal.
Setiap potongan mengunggah `.artifacts/docker-tests/` dengan log lane, pengukuran waktu, `summary.json`, `failures.json`, pengukuran waktu fase, JSON rencana scheduler, tabel lane lambat, dan perintah pengulangan per lane. Input `docker_lanes` workflow menjalankan lane yang dipilih terhadap image yang sudah disiapkan, bukan job potongan, sehingga debug lane yang gagal tetap terbatas pada satu job Docker yang ditargetkan dan menyiapkan, mengunduh, atau menggunakan ulang artefak paket untuk run tersebut; jika lane yang dipilih adalah lane Docker live, job yang ditargetkan membangun image uji live secara lokal untuk pengulangan itu. Perintah pengulangan GitHub per lane yang dihasilkan menyertakan `package_artifact_run_id`, `package_artifact_name`, dan input image yang disiapkan saat nilai-nilai tersebut ada, sehingga lane yang gagal dapat menggunakan ulang paket dan image persis dari run yang gagal.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
Alur kerja live/E2E terjadwal menjalankan suite Docker jalur rilis penuh setiap hari.
Workflow live/E2E terjadwal menjalankan suite Docker jalur rilis penuh setiap hari.
## Prarilis Plugin
`Plugin Prerelease` adalah cakupan produk/paket yang lebih mahal, jadi ini adalah alur kerja terpisah yang di-dispatch oleh `Full Release Validation` atau oleh operator eksplisit. Pull request normal, push `main`, dan dispatch CI manual mandiri membiarkan suite tersebut nonaktif. Suite ini menyeimbangkan pengujian Plugin bawaan di delapan worker ekstensi; job shard ekstensi tersebut menjalankan hingga dua grup konfigurasi Plugin sekaligus dengan satu worker Vitest per grup dan heap Node yang lebih besar agar batch Plugin yang berat impor tidak membuat job CI tambahan.
`Plugin Prerelease` adalah cakupan produk/paket yang lebih mahal, sehingga menjadi workflow terpisah yang di-dispatch oleh `Full Release Validation` atau oleh operator eksplisit. Pull request normal, push `main`, dan dispatch CI manual mandiri tidak menjalankan suite tersebut. Workflow ini menyeimbangkan pengujian Plugin bawaan di delapan worker ekstensi; job shard ekstensi tersebut menjalankan hingga dua grup konfigurasi Plugin sekaligus dengan satu worker Vitest per grup dan heap Node yang lebih besar agar batch Plugin yang berat impor tidak membuat job CI tambahan.
## QA Lab
QA Lab memiliki lane CI khusus di luar alur kerja utama yang dicakup secara cerdas.
QA Lab memiliki lane CI khusus di luar workflow utama yang dicakup cerdas.
- Alur kerja `Parity gate` berjalan pada perubahan PR yang cocok dan dispatch manual; alur kerja ini membangun runtime QA privat dan membandingkan pack agentik mock GPT-5.5 dan Opus 4.6.
- Alur kerja `QA-Lab - All Lanes` berjalan setiap malam pada `main` dan pada dispatch manual; alur kerja ini menyebarkan mock parity gate, lane Matrix live, serta lane Telegram dan Discord live sebagai job paralel. Job live menggunakan environment `qa-live-shared`, dan Telegram/Discord menggunakan lease Convex.
- Workflow `Parity gate` berjalan pada perubahan PR yang cocok dan dispatch manual; workflow ini membangun runtime QA privat dan membandingkan paket agentic GPT-5.5 dan Opus 4.6 tiruan.
- Workflow `QA-Lab - All Lanes` berjalan setiap malam pada `main` dan pada dispatch manual; workflow ini menyebarkan parity gate tiruan, lane Matrix live, serta lane Telegram dan Discord live sebagai job paralel. Job live menggunakan environment `qa-live-shared`, dan Telegram/Discord menggunakan lease Convex.
Pemeriksaan rilis menjalankan lane transport Matrix dan Telegram live dengan provider mock deterministik dan model berkualifikasi mock (`mock-openai/gpt-5.5` dan `mock-openai/gpt-5.5-alt`) sehingga kontrak channel terisolasi dari latensi model live dan startup provider-plugin normal. Gateway transport live menonaktifkan pencarian memori karena paritas QA mencakup perilaku memori secara terpisah; konektivitas provider dicakup oleh suite model live, provider native, dan provider Docker yang terpisah.
Pemeriksaan rilis menjalankan lane transport Matrix dan Telegram live dengan penyedia tiruan deterministik dan model yang memenuhi syarat tiruan (`mock-openai/gpt-5.5` dan `mock-openai/gpt-5.5-alt`) sehingga kontrak channel terisolasi dari latensi model live dan startup Plugin penyedia normal. Gateway transport live menonaktifkan pencarian memori karena paritas QA mencakup perilaku memori secara terpisah; konektivitas penyedia dicakup oleh suite model live, penyedia native, dan penyedia Docker yang terpisah.
Matrix menggunakan `--profile fast` untuk gate terjadwal dan rilis, menambahkan `--fail-fast` hanya ketika CLI yang di-checkout mendukungnya. Default CLI dan input alur kerja manual tetap `all`; dispatch manual `matrix_profile=all` selalu membagi cakupan Matrix penuh menjadi job `transport`, `media`, `e2ee-smoke`, `e2ee-deep`, dan `e2ee-cli`.
Matrix menggunakan `--profile fast` untuk gate terjadwal dan rilis, dengan menambahkan `--fail-fast` hanya saat CLI yang di-checkout mendukungnya. Default CLI dan input workflow manual tetap `all`; dispatch manual `matrix_profile=all` selalu memecah cakupan Matrix penuh ke dalam job `transport`, `media`, `e2ee-smoke`, `e2ee-deep`, dan `e2ee-cli`.
`OpenClaw Release Checks` juga menjalankan lane QA Lab yang kritis untuk rilis sebelum persetujuan rilis; parity gate QA-nya menjalankan pack kandidat dan baseline sebagai job lane paralel, lalu mengunduh kedua artefak ke job laporan kecil untuk perbandingan paritas akhir.
`OpenClaw Release Checks` juga menjalankan lane QA Lab yang kritis untuk rilis sebelum persetujuan rilis; parity gate QA-nya menjalankan paket kandidat dan baseline sebagai job lane paralel, lalu mengunduh kedua artefak ke dalam job laporan kecil untuk perbandingan paritas akhir.
Jangan menempatkan jalur landing PR di balik `Parity gate` kecuali perubahan benar-benar menyentuh runtime QA, paritas model-pack, atau permukaan yang dimiliki alur kerja paritas. Untuk perbaikan channel, konfigurasi, dokumen, atau unit-test normal, perlakukan ini sebagai sinyal opsional dan ikuti bukti CI/check yang dicakup.
Jangan letakkan jalur landing PR di belakang `Parity gate` kecuali perubahan benar-benar menyentuh runtime QA, paritas paket model, atau permukaan yang dimiliki workflow paritas. Untuk perbaikan channel, konfigurasi, dokumentasi, atau unit test normal, perlakukan itu sebagai sinyal opsional dan ikuti bukti CI/pemeriksaan yang dicakup.
## CodeQL
Alur kerja `CodeQL` sengaja menjadi pemindai keamanan pass pertama yang sempit, bukan sweep repositori penuh. Run harian, manual, dan guard pull request non-draft memindai kode alur kerja Actions ditambah permukaan JavaScript/TypeScript berisiko tertinggi dengan kueri keamanan keyakinan tinggi yang difilter ke `security-severity` tinggi/kritis.
Workflow `CodeQL` sengaja merupakan pemindai keamanan tahap pertama yang sempit, bukan sweep repositori penuh. Run harian, manual, dan penjaga pull request non-draft memindai kode workflow Actions ditambah permukaan JavaScript/TypeScript berisiko tertinggi dengan kueri keamanan berkeyakinan tinggi yang difilter ke `security-severity` tinggi/kritis.
Guard pull request tetap ringan: ini hanya dimulai untuk perubahan di bawah `.github/actions`, `.github/codeql`, `.github/workflows`, `packages`, atau `src`, dan menjalankan matriks keamanan keyakinan tinggi yang sama seperti alur kerja terjadwal. CodeQL Android dan macOS tetap di luar default PR.
Penjaga pull request tetap ringan: hanya dimulai untuk perubahan di bawah `.github/actions`, `.github/codeql`, `.github/workflows`, `packages`, atau `src`, dan menjalankan matriks keamanan berkeyakinan tinggi yang sama seperti workflow terjadwal. CodeQL Android dan macOS tetap berada di luar default PR.
### Kategori keamanan
| Kategori | Permukaan |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, rahasia, sandbox, cron, dan baseline gateway |
| `/codeql-security-high/channel-runtime-boundary` | Kontrak implementasi channel inti ditambah runtime Plugin channel, gateway, Plugin SDK, rahasia, titik sentuh audit |
| `/codeql-security-high/network-ssrf-boundary` | Permukaan kebijakan SSRF inti, parsing IP, network guard, web-fetch, dan SSRF Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Server MCP, helper eksekusi proses, pengiriman keluar, dan gate eksekusi tool agen |
| `/codeql-security-high/plugin-trust-boundary` | Permukaan kepercayaan kontrak paket instalasi Plugin, loader, manifest, registry, staging dependensi runtime, pemuatan sumber, dan Plugin SDK |
| `/codeql-security-high/core-auth-secrets` | Auth, secret, sandbox, cron, dan baseline gateway |
| `/codeql-security-high/channel-runtime-boundary` | Kontrak implementasi channel inti ditambah runtime Plugin channel, Gateway, Plugin SDK, secret, titik sentuh audit |
| `/codeql-security-high/network-ssrf-boundary` | Permukaan SSRF inti, parsing IP, penjaga jaringan, web-fetch, dan kebijakan SSRF Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Server MCP, helper eksekusi proses, pengiriman keluar, dan gate eksekusi tool agent |
| `/codeql-security-high/plugin-trust-boundary` | Permukaan trust instalasi Plugin, loader, manifes, registry, staging dependensi runtime, pemuatan sumber, dan kontrak paket Plugin SDK |
### Shard keamanan khusus platform
- `CodeQL Android Critical Security` — shard keamanan Android terjadwal. Membangun aplikasi Android secara manual untuk CodeQL pada runner Blacksmith Linux terkecil yang diterima oleh sanity alur kerja. Mengunggah di bawah `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard keamanan macOS mingguan/manual. Membangun aplikasi macOS secara manual untuk CodeQL di Blacksmith macOS, memfilter hasil build dependensi keluar dari SARIF yang diunggah, dan mengunggah di bawah `/codeql-critical-security/macos`. Disimpan di luar default harian karena build macOS mendominasi runtime bahkan saat bersih.
- `CodeQL Android Critical Security` — shard keamanan Android terjadwal. Membangun aplikasi Android secara manual untuk CodeQL pada runner Blacksmith Linux terkecil yang diterima oleh kewajaran workflow. Mengunggah di bawah `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard keamanan macOS mingguan/manual. Membangun aplikasi macOS secara manual untuk CodeQL pada Blacksmith macOS, memfilter hasil build dependensi dari SARIF yang diunggah, dan mengunggah di bawah `/codeql-critical-security/macos`. Dipertahankan di luar default harian karena build macOS mendominasi runtime bahkan saat bersih.
### Kategori Critical Quality
### Kategori Kualitas Kritis
`CodeQL Critical Quality` adalah shard non-keamanan yang sepadan. Ini hanya menjalankan kueri kualitas JavaScript/TypeScript non-keamanan dengan severity error di atas permukaan bernilai tinggi yang sempit pada runner Blacksmith Linux yang lebih kecil. Guard pull request-nya sengaja lebih kecil daripada profil terjadwal: PR non-draft hanya menjalankan shard `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract`, dan `plugin-sdk-reply-runtime` yang cocok untuk perubahan kode eksekusi command/model/tool agen dan dispatch balasan, kode skema/migrasi/IO konfigurasi, kode auth/rahasia/sandbox/keamanan, runtime channel inti dan Plugin channel bawaan, protokol Gateway/server-method, glue runtime memori/SDK, MCP/proses/pengiriman keluar, runtime provider/katalog model, diagnostik sesi/antrean pengiriman, loader Plugin, kontrak paket/Plugin SDK, atau runtime balasan Plugin SDK. Perubahan konfigurasi CodeQL dan alur kerja kualitas menjalankan semua dua belas shard kualitas PR.
`CodeQL Critical Quality` adalah shard non-keamanan yang sepadan. Shard ini hanya menjalankan kueri kualitas JavaScript/TypeScript non-keamanan dengan tingkat error-severity di atas permukaan sempit bernilai tinggi pada runner Blacksmith Linux yang lebih kecil. Penjaga pull request-nya sengaja lebih kecil daripada profil terjadwal: PR non-draft hanya menjalankan shard `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract`, dan `plugin-sdk-reply-runtime` yang cocok untuk perubahan kode eksekusi perintah/model/tool agent dan dispatch balasan, kode skema/migrasi/IO konfigurasi, kode auth/secret/sandbox/keamanan, runtime channel inti dan Plugin channel bawaan, protokol/metode server Gateway, perekat runtime/SDK memori, MCP/proses/pengiriman keluar, katalog model/runtime penyedia, diagnostik sesi/antrian pengiriman, loader Plugin, kontrak paket/Plugin SDK, atau runtime balasan Plugin SDK. Perubahan konfigurasi CodeQL dan workflow kualitas menjalankan seluruh dua belas shard kualitas PR.
Dispatch manual menerima:
@ -352,38 +352,38 @@ profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-run
Profil sempit adalah hook pengajaran/iterasi untuk menjalankan satu shard kualitas secara terisolasi.
| Kategori | Permukaan |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Auth, secret, sandbox, cron, dan kode batas keamanan gateway |
| `/codeql-critical-quality/config-boundary` | Skema konfigurasi, migrasi, normalisasi, dan kontrak IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Skema protokol Gateway dan kontrak metode server |
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrak implementasi kanal inti dan Plugin kanal bawaan |
| `/codeql-critical-quality/agent-runtime-boundary` | Eksekusi perintah, dispatch model/provider, dispatch dan antrean balasan otomatis, serta kontrak runtime control-plane ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Server MCP dan bridge tool, helper supervisi proses, dan kontrak pengiriman keluar |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK host memori, facade runtime memori, alias SDK Plugin memori, glue aktivasi runtime memori, dan perintah doctor memori |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internal antrean balasan, antrean pengiriman sesi, helper binding/pengiriman sesi keluar, permukaan bundel event/log diagnostik, dan kontrak CLI doctor sesi |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch balasan masuk SDK Plugin, helper payload/chunking/runtime balasan, opsi balasan kanal, antrean pengiriman, dan helper binding sesi/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisasi katalog model, auth dan discovery provider, registrasi runtime provider, default/katalog provider, serta registry web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap UI kontrol, persistensi lokal, alur kontrol Gateway, dan kontrak runtime control-plane tugas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Kontrak runtime fetch/search web inti, IO media, pemahaman media, pembuatan gambar, dan pembuatan media |
| `/codeql-critical-quality/plugin-boundary` | Kontrak loader, registry, permukaan publik, dan entrypoint SDK Plugin |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Sumber SDK Plugin sisi paket yang dipublikasikan dan helper kontrak paket Plugin |
| Kategori | Permukaan |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Kode batas keamanan autentikasi, rahasia, sandbox, Cron, dan Gateway |
| `/codeql-critical-quality/config-boundary` | Skema konfigurasi, migrasi, normalisasi, dan kontrak IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Skema protokol Gateway dan kontrak metode server |
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrak implementasi kanal inti dan Plugin kanal bawaan |
| `/codeql-critical-quality/agent-runtime-boundary` | Eksekusi perintah, dispatch model/penyedia, dispatch dan antrean balasan otomatis, serta kontrak runtime bidang kontrol ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Server MCP dan jembatan alat, pembantu pengawasan proses, serta kontrak pengiriman keluar |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK host memori, fasad runtime memori, alias SDK Plugin memori, perekat aktivasi runtime memori, dan perintah doctor memori |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internal antrean balasan, antrean pengiriman sesi, pembantu pengikatan/pengiriman sesi keluar, permukaan bundel peristiwa/log diagnostik, dan kontrak CLI doctor sesi |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch balasan masuk SDK Plugin, pembantu payload/pemotongan/runtime balasan, opsi balasan kanal, antrean pengiriman, dan pembantu pengikatan sesi/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisasi katalog model, autentikasi dan penemuan penyedia, pendaftaran runtime penyedia, default/katalog penyedia, serta registri web/pencarian/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap UI kontrol, persistensi lokal, alur kontrol Gateway, dan kontrak runtime bidang kontrol tugas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Fetch/pencarian web inti, IO media, pemahaman media, pembuatan gambar, dan kontrak runtime pembuatan media |
| `/codeql-critical-quality/plugin-boundary` | Kontrak loader, registri, permukaan publik, dan entrypoint SDK Plugin |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Sumber SDK Plugin sisi paket yang dipublikasikan dan pembantu kontrak paket Plugin |
Kualitas tetap dipisahkan dari keamanan agar temuan kualitas dapat dijadwalkan, diukur, dinonaktifkan, atau diperluas tanpa mengaburkan sinyal keamanan. Ekspansi CodeQL untuk Swift, Python, dan Plugin bawaan harus ditambahkan kembali sebagai pekerjaan lanjutan yang berscope atau dishard hanya setelah profil sempit memiliki runtime dan sinyal yang stabil.
Kualitas tetap terpisah dari keamanan agar temuan kualitas dapat dijadwalkan, diukur, dinonaktifkan, atau diperluas tanpa mengaburkan sinyal keamanan. Perluasan CodeQL untuk Swift, Python, dan Plugin bawaan sebaiknya ditambahkan kembali sebagai pekerjaan lanjutan yang terskop atau di-shard hanya setelah profil sempit memiliki runtime dan sinyal yang stabil.
## Alur kerja pemeliharaan
### Docs Agent
### Agen Docs
Workflow `Docs Agent` adalah lane pemeliharaan Codex berbasis event untuk menjaga dokumen yang ada tetap selaras dengan perubahan yang baru landed. Ini tidak memiliki jadwal murni: run CI push non-bot yang berhasil di `main` dapat memicunya, dan dispatch manual dapat menjalankannya langsung. Invokasi workflow-run dilewati ketika `main` sudah bergerak maju atau ketika run Docs Agent non-skipped lain dibuat dalam satu jam terakhir. Saat berjalan, workflow ini meninjau rentang commit dari SHA sumber Docs Agent non-skipped sebelumnya hingga `main` saat ini, sehingga satu run per jam dapat mencakup semua perubahan main yang terkumpul sejak pass dokumen terakhir.
Alur kerja `Docs Agent` adalah jalur pemeliharaan Codex berbasis peristiwa untuk menjaga dokumen yang ada tetap selaras dengan perubahan yang baru saja masuk. Alur ini tidak memiliki jadwal murni: run CI push non-bot yang berhasil di `main` dapat memicunya, dan dispatch manual dapat menjalankannya langsung. Invokasi workflow-run dilewati ketika `main` sudah bergerak maju atau ketika run Docs Agent non-dilewati lain dibuat dalam satu jam terakhir. Saat berjalan, alur ini meninjau rentang commit dari SHA sumber Docs Agent non-dilewati sebelumnya hingga `main` saat ini, sehingga satu run per jam dapat mencakup semua perubahan main yang terkumpul sejak pemeriksaan dokumen terakhir.
### Test Performance Agent
### Agen Performa Pengujian
Workflow `Test Performance Agent` adalah lane pemeliharaan Codex berbasis event untuk pengujian lambat. Ini tidak memiliki jadwal murni: run CI push non-bot yang berhasil di `main` dapat memicunya, tetapi akan dilewati jika invokasi workflow-run lain sudah berjalan atau sedang berjalan pada hari UTC tersebut. Dispatch manual melewati gate aktivitas harian itu. Lane ini membuat laporan performa Vitest full-suite yang dikelompokkan, mengizinkan Codex hanya membuat perbaikan performa pengujian kecil yang mempertahankan coverage alih-alih refactor luas, lalu menjalankan ulang laporan full-suite dan menolak perubahan yang mengurangi jumlah baseline pengujian yang lulus. Jika baseline memiliki pengujian yang gagal, Codex hanya boleh memperbaiki kegagalan yang jelas dan laporan full-suite setelah agent harus lulus sebelum apa pun di-commit. Saat `main` maju sebelum push bot landed, lane ini me-rebase patch yang sudah divalidasi, menjalankan ulang `pnpm check:changed`, dan mencoba ulang push; patch stale yang konflik dilewati. Lane ini menggunakan Ubuntu yang di-host GitHub sehingga action Codex dapat mempertahankan postur keselamatan drop-sudo yang sama seperti docs agent.
Alur kerja `Test Performance Agent` adalah jalur pemeliharaan Codex berbasis peristiwa untuk pengujian yang lambat. Alur ini tidak memiliki jadwal murni: run CI push non-bot yang berhasil di `main` dapat memicunya, tetapi alur ini melewati eksekusi jika invokasi workflow-run lain sudah berjalan atau sedang berjalan pada hari UTC tersebut. Dispatch manual melewati gerbang aktivitas harian itu. Jalur ini membangun laporan performa Vitest full-suite yang dikelompokkan, membiarkan Codex hanya membuat perbaikan performa pengujian kecil yang mempertahankan cakupan, bukan refactor luas, lalu menjalankan ulang laporan full-suite dan menolak perubahan yang mengurangi jumlah baseline pengujian yang lulus. Jika baseline memiliki pengujian yang gagal, Codex hanya boleh memperbaiki kegagalan yang jelas dan laporan full-suite setelah agen harus lulus sebelum apa pun di-commit. Ketika `main` maju sebelum push bot masuk, jalur ini melakukan rebase pada patch yang telah divalidasi, menjalankan ulang `pnpm check:changed`, dan mencoba ulang push; patch basi yang konflik dilewati. Alur ini menggunakan Ubuntu yang di-host GitHub sehingga action Codex dapat mempertahankan postur keamanan drop-sudo yang sama seperti agen docs.
### PR Duplikat Setelah Merge
Workflow `Duplicate PRs After Merge` adalah workflow maintainer manual untuk pembersihan duplikat pasca-land. Default-nya adalah dry-run dan hanya menutup PR yang dicantumkan secara eksplisit ketika `apply=true`. Sebelum mengubah GitHub, workflow ini memverifikasi bahwa PR yang landed sudah di-merge dan setiap duplikat memiliki issue rujukan bersama atau hunk perubahan yang tumpang tindih.
Alur kerja `Duplicate PRs After Merge` adalah alur kerja maintainer manual untuk pembersihan duplikat setelah land. Default-nya adalah dry-run dan hanya menutup PR yang tercantum secara eksplisit saat `apply=true`. Sebelum memutasi GitHub, alur ini memverifikasi bahwa PR yang di-land sudah di-merge dan setiap duplikat memiliki issue rujukan bersama atau hunk perubahan yang tumpang tindih.
```bash
gh workflow run duplicate-after-merge.yml \
@ -392,29 +392,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Gate pemeriksaan lokal dan routing perubahan
## Gerbang pemeriksaan lokal dan routing perubahan
Logika changed-lane lokal berada di `scripts/changed-lanes.mjs` dan dieksekusi oleh `scripts/check-changed.mjs`. Gate pemeriksaan lokal itu lebih ketat terhadap batas arsitektur daripada cakupan platform CI yang luas:
Logika changed-lane lokal berada di `scripts/changed-lanes.mjs` dan dieksekusi oleh `scripts/check-changed.mjs`. Gerbang pemeriksaan lokal tersebut lebih ketat tentang batas arsitektur dibandingkan cakupan platform CI yang luas:
- perubahan produksi inti menjalankan typecheck prod inti dan pengujian inti plus lint/guard inti;
- perubahan khusus pengujian inti hanya menjalankan typecheck pengujian inti plus lint inti;
- perubahan hanya pengujian inti hanya menjalankan typecheck pengujian inti plus lint inti;
- perubahan produksi ekstensi menjalankan typecheck prod ekstensi dan pengujian ekstensi plus lint ekstensi;
- perubahan khusus pengujian ekstensi menjalankan typecheck pengujian ekstensi plus lint ekstensi;
- perubahan SDK Plugin publik atau kontrak Plugin meluas ke typecheck ekstensi karena ekstensi bergantung pada kontrak inti tersebut (sweep ekstensi Vitest tetap menjadi pekerjaan pengujian eksplisit);
- bump versi metadata-only rilis menjalankan pemeriksaan versi/konfigurasi/dependensi-root yang tertarget;
- perubahan root/konfigurasi yang tidak diketahui fail safe ke semua lane pemeriksaan.
- perubahan hanya pengujian ekstensi menjalankan typecheck pengujian ekstensi plus lint ekstensi;
- perubahan SDK Plugin publik atau kontrak plugin meluas ke typecheck ekstensi karena ekstensi bergantung pada kontrak inti tersebut (sweep ekstensi Vitest tetap menjadi pekerjaan pengujian eksplisit);
- bump versi metadata rilis saja menjalankan pemeriksaan versi/konfigurasi/dependensi-root yang ditargetkan;
- perubahan root/konfigurasi yang tidak diketahui fail safe ke semua jalur pemeriksaan.
Routing changed-test lokal berada di `scripts/test-projects.test-support.mjs` dan sengaja lebih murah daripada `check:changed`: edit pengujian langsung menjalankan dirinya sendiri, edit sumber mengutamakan pemetaan eksplisit, lalu pengujian sibling dan dependent import-graph. Konfigurasi pengiriman group-room bersama adalah salah satu pemetaan eksplisit: perubahan pada konfigurasi balasan yang terlihat grup, mode pengiriman balasan sumber, atau prompt sistem message-tool diarahkan melalui pengujian balasan inti plus regresi pengiriman Discord dan Slack sehingga perubahan default bersama gagal sebelum push PR pertama. Gunakan `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` hanya ketika perubahan cukup luas pada harness sehingga set terpetakan murah bukan proxy yang tepercaya.
Routing changed-test lokal berada di `scripts/test-projects.test-support.mjs` dan secara sengaja lebih murah daripada `check:changed`: edit pengujian langsung menjalankan dirinya sendiri, edit sumber mengutamakan pemetaan eksplisit, lalu pengujian saudara dan dependen grafik impor. Konfigurasi pengiriman group-room bersama adalah salah satu pemetaan eksplisit: perubahan pada konfigurasi balasan terlihat grup, mode pengiriman balasan sumber, atau prompt sistem alat pesan dirutekan melalui pengujian balasan inti plus regresi pengiriman Discord dan Slack sehingga perubahan default bersama gagal sebelum push PR pertama. Gunakan `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` hanya ketika perubahan cukup luas di seluruh harness sehingga set murah yang dipetakan bukan proksi yang dapat dipercaya.
## Validasi Testbox
Jalankan Testbox dari root repo dan utamakan box warmed baru untuk bukti luas. Sebelum menghabiskan gate lambat pada box yang digunakan ulang, kedaluwarsa, atau baru saja melaporkan sync yang sangat besar, jalankan `pnpm testbox:sanity` di dalam box terlebih dahulu.
Jalankan Testbox dari root repo dan utamakan box baru yang sudah dihangatkan untuk bukti luas. Sebelum menghabiskan gerbang lambat pada box yang digunakan ulang, kedaluwarsa, atau baru melaporkan sinkronisasi yang sangat besar, jalankan `pnpm testbox:sanity` di dalam box terlebih dahulu.
Pemeriksaan sanity gagal cepat ketika file root wajib seperti `pnpm-lock.yaml` menghilang atau ketika `git status --short` menunjukkan setidaknya 200 penghapusan terlacak. Itu biasanya berarti status sync remote bukan salinan PR yang tepercaya; hentikan box itu dan warm box baru alih-alih men-debug kegagalan pengujian produk. Untuk PR penghapusan besar yang disengaja, setel `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` untuk run sanity tersebut.
Pemeriksaan sanity gagal cepat ketika file root yang diperlukan seperti `pnpm-lock.yaml` hilang atau ketika `git status --short` menampilkan setidaknya 200 penghapusan terlacak. Itu biasanya berarti status sinkronisasi jarak jauh bukan salinan PR yang dapat dipercaya; hentikan box tersebut dan hangatkan yang baru, alih-alih men-debug kegagalan pengujian produk. Untuk PR penghapusan besar yang disengaja, setel `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` untuk run sanity tersebut.
`pnpm testbox:run` juga menghentikan invokasi CLI Blacksmith lokal yang tetap berada di fase sync selama lebih dari lima menit tanpa output pasca-sync. Setel `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` untuk menonaktifkan guard itu, atau gunakan nilai milidetik yang lebih besar untuk diff lokal yang sangat besar.
`pnpm testbox:run` juga menghentikan invokasi CLI Blacksmith lokal yang tetap berada dalam fase sinkronisasi selama lebih dari lima menit tanpa output pasca-sinkronisasi. Setel `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` untuk menonaktifkan guard tersebut, atau gunakan nilai milidetik yang lebih besar untuk diff lokal yang luar biasa besar.
## Terkait
- [Ringkasan instalasi](/id/install)
- [Ikhtisar instalasi](/id/install)
- [Kanal pengembangan](/id/install/development-channels)

137
docs/id/concepts/agent-loop.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Anda membutuhkan panduan langkah demi langkah yang tepat tentang perulangan agen atau peristiwa siklus hidup
- Anda mengubah pengantrean sesi, penulisan transkrip, atau perilaku kunci tulis sesi
summary: Siklus hidup perulangan agen, aliran, dan semantik menunggu
- Anda membutuhkan panduan langkah demi langkah yang tepat tentang loop agen atau peristiwa siklus hidup
- Anda sedang mengubah antrean sesi, penulisan transkrip, atau perilaku kunci tulis sesi
summary: Siklus hidup loop agen, aliran, dan semantik menunggu
title: Siklus agen
x-i18n:
generated_at: "2026-04-30T09:42:14Z"
generated_at: "2026-04-30T18:38:55Z"
model: gpt-5.5
provider: openai
source_hash: 902d543bd71dd517a810d825cbe92e244fe89230f47eeada72477c657a2bec32
source_hash: 5466893253e1f82482284ff82db56f4c3fca018bf12e4114fad76d37cad954df
source_path: concepts/agent-loop.md
workflow: 16
---
Loop agentik adalah keseluruhan eksekusi “nyata” sebuah agen: penerimaan → perakitan konteks → inferensi model →
eksekusi alat → balasan streaming → persistensi. Ini adalah jalur otoritatif yang mengubah pesan
Loop agentik adalah proses jalan “nyata” penuh dari sebuah agen: penerimaan → perakitan konteks → inferensi model →
eksekusi alat → balasan streaming → persistensi. Ini adalah jalur otoritatif yang mengubah sebuah pesan
menjadi tindakan dan balasan akhir, sambil menjaga status sesi tetap konsisten.
Di OpenClaw, loop adalah satu eksekusi terserialisasi per sesi yang memancarkan peristiwa siklus hidup dan stream
saat model berpikir, memanggil alat, dan men-stream keluaran. Dokumen ini menjelaskan bagaimana loop autentik itu
Di OpenClaw, sebuah loop adalah satu proses jalan terserialisasi per sesi yang memancarkan peristiwa siklus hidup dan stream
saat model berpikir, memanggil alat, dan melakukan streaming keluaran. Dokumen ini menjelaskan bagaimana loop autentik tersebut
dirangkai dari ujung ke ujung.
## Titik masuk
@ -28,55 +28,56 @@ dirangkai dari ujung ke ujung.
## Cara kerjanya (tingkat tinggi)
1. RPC `agent` memvalidasi parameter, me-resolve sesi (sessionKey/sessionId), mempersistenkan metadata sesi, mengembalikan `{ runId, acceptedAt }` segera.
1. RPC `agent` memvalidasi parameter, menyelesaikan sesi (sessionKey/sessionId), mempersistensikan metadata sesi, dan langsung mengembalikan `{ runId, acceptedAt }`.
2. `agentCommand` menjalankan agen:
- me-resolve default model + thinking/verbose/trace
- memuat snapshot Skills
- menyelesaikan model + default thinking/verbose/trace
- memuat snapshot skills
- memanggil `runEmbeddedPiAgent` (runtime pi-agent-core)
- memancarkan **akhir/kesalahan siklus hidup** jika loop tersemat tidak memancarkannya
- memancarkan **lifecycle end/error** jika loop tertanam tidak memancarkannya
3. `runEmbeddedPiAgent`:
- menserialisasi eksekusi melalui antrean per-sesi + global
- me-resolve model + profil auth dan membangun sesi pi
- berlangganan peristiwa pi dan men-stream delta asisten/alat
- menerapkan timeout -> membatalkan eksekusi jika terlampaui
- menserialkan proses jalan melalui antrean per sesi + global
- menyelesaikan model + profil autentikasi dan membangun sesi pi
- berlangganan ke peristiwa pi dan melakukan streaming delta asisten/alat
- menerapkan timeout -> membatalkan proses jalan jika terlampaui
- untuk giliran server aplikasi Codex, membatalkan giliran yang diterima jika berhenti menghasilkan progres server aplikasi sebelum peristiwa terminal
- mengembalikan payload + metadata penggunaan
4. `subscribeEmbeddedPiSession` menjembatani peristiwa pi-agent-core ke stream `agent` OpenClaw:
- peristiwa alat => `stream: "tool"`
- delta asisten => `stream: "assistant"`
- peristiwa siklus hidup => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. `agent.wait` menggunakan `waitForAgentRun`:
- menunggu **akhir/kesalahan siklus hidup** untuk `runId`
- menunggu **lifecycle end/error** untuk `runId`
- mengembalikan `{ status: ok|error|timeout, startedAt, endedAt, error? }`
## Antrean + konkurensi
- Eksekusi diserialisasi per kunci sesi (jalur sesi) dan secara opsional melalui jalur global.
- Proses jalan diserialkan per kunci sesi (jalur sesi) dan secara opsional melalui jalur global.
- Ini mencegah race alat/sesi dan menjaga riwayat sesi tetap konsisten.
- Kanal pesan dapat memilih mode antrean (collect/steer/followup) yang memberi masukan ke sistem jalur ini.
- Kanal perpesanan dapat memilih mode antrean (collect/steer/followup) yang masuk ke sistem jalur ini.
Lihat [Antrean Perintah](/id/concepts/queue).
- Penulisan transkrip juga dilindungi oleh kunci tulis sesi pada file sesi. Kunci tersebut
sadar proses dan berbasis file, sehingga menangkap penulis yang melewati antrean dalam-proses atau berasal dari
- Penulisan transkrip juga dilindungi oleh kunci tulis sesi pada file sesi. Kunci ini
sadar proses dan berbasis file, sehingga dapat menangkap penulis yang melewati antrean dalam proses atau berasal dari
proses lain.
- Kunci tulis sesi secara default tidak reentrant. Jika helper sengaja menumpuk akuisisi
- Kunci tulis sesi secara default tidak reentrant. Jika helper secara sengaja menumpuk akuisisi
kunci yang sama sambil mempertahankan satu penulis logis, helper tersebut harus ikut serta secara eksplisit dengan
`allowReentrant: true`.
## Persiapan sesi + workspace
- Workspace di-resolve dan dibuat; eksekusi sandbox dapat diarahkan ulang ke root workspace sandbox.
- Skills dimuat (atau digunakan ulang dari snapshot) dan disuntikkan ke env dan prompt.
- File bootstrap/konteks di-resolve dan disuntikkan ke laporan prompt sistem.
- Kunci tulis sesi diambil; `SessionManager` dibuka dan disiapkan sebelum streaming. Setiap
jalur penulisan ulang transkrip, Compaction, atau pemangkasan berikutnya harus mengambil kunci yang sama sebelum membuka atau
- Workspace diselesaikan dan dibuat; proses jalan sandbox dapat dialihkan ke root workspace sandbox.
- Skills dimuat (atau digunakan ulang dari snapshot) dan diinjeksi ke env dan prompt.
- File bootstrap/konteks diselesaikan dan diinjeksi ke laporan prompt sistem.
- Kunci tulis sesi diperoleh; `SessionManager` dibuka dan disiapkan sebelum streaming. Setiap
jalur penulisan ulang transkrip, compaction, atau pemotongan berikutnya harus mengambil kunci yang sama sebelum membuka atau
memutasi file transkrip.
## Perakitan prompt + prompt sistem
- Prompt sistem dibangun dari prompt dasar OpenClaw, prompt Skills, konteks bootstrap, dan override per-eksekusi.
- Batas khusus model dan token cadangan Compaction diterapkan.
- Prompt sistem dibangun dari prompt dasar OpenClaw, prompt skills, konteks bootstrap, dan override per proses jalan.
- Batas spesifik model dan token cadangan compaction diterapkan.
- Lihat [Prompt sistem](/id/concepts/system-prompt) untuk apa yang dilihat model.
## Titik hook (tempat Anda dapat mengintersepsi)
## Titik hook (tempat Anda dapat mengintersep)
OpenClaw memiliki dua sistem hook:
@ -95,66 +96,66 @@ Lihat [Hook](/id/automation/hooks) untuk penyiapan dan contoh.
Ini berjalan di dalam loop agen atau pipeline gateway:
- **`before_model_resolve`**: berjalan pra-sesi (tanpa `messages`) untuk meng-override penyedia/model secara deterministik sebelum resolusi model.
- **`before_prompt_build`**: berjalan setelah pemuatan sesi (dengan `messages`) untuk menyuntikkan `prependContext`, `systemPrompt`, `prependSystemContext`, atau `appendSystemContext` sebelum pengiriman prompt. Gunakan `prependContext` untuk teks dinamis per-giliran dan field konteks sistem untuk panduan stabil yang harus berada di ruang prompt sistem.
- **`before_agent_start`**: hook kompatibilitas lama yang dapat berjalan di salah satu fase; lebih pilih hook eksplisit di atas.
- **`before_agent_reply`**: berjalan setelah tindakan inline dan sebelum panggilan LLM, memungkinkan Plugin mengklaim giliran dan mengembalikan balasan sintetis atau membungkam giliran sepenuhnya.
- **`agent_end`**: memeriksa daftar pesan akhir dan metadata eksekusi setelah selesai.
- **`before_compaction` / `after_compaction`**: mengamati atau menganotasi siklus Compaction.
- **`before_tool_call` / `after_tool_call`**: mengintersepsi parameter/hasil alat.
- **`before_model_resolve`**: berjalan sebelum sesi (tanpa `messages`) untuk secara deterministik meng-override penyedia/model sebelum resolusi model.
- **`before_prompt_build`**: berjalan setelah sesi dimuat (dengan `messages`) untuk menginjeksi `prependContext`, `systemPrompt`, `prependSystemContext`, atau `appendSystemContext` sebelum pengiriman prompt. Gunakan `prependContext` untuk teks dinamis per giliran dan kolom konteks sistem untuk panduan stabil yang harus berada di ruang prompt sistem.
- **`before_agent_start`**: hook kompatibilitas lama yang dapat berjalan di salah satu fase; utamakan hook eksplisit di atas.
- **`before_agent_reply`**: berjalan setelah tindakan inline dan sebelum panggilan LLM, memungkinkan Plugin mengklaim giliran dan mengembalikan balasan sintetis atau sepenuhnya membisukan giliran.
- **`agent_end`**: memeriksa daftar pesan akhir dan metadata proses jalan setelah selesai.
- **`before_compaction` / `after_compaction`**: mengamati atau menganotasi siklus compaction.
- **`before_tool_call` / `after_tool_call`**: mengintersep parameter/hasil alat.
- **`before_install`**: memeriksa temuan pemindaian bawaan dan secara opsional memblokir pemasangan skill atau Plugin.
- **`tool_result_persist`**: mentransformasi hasil alat secara sinkron sebelum ditulis ke transkrip sesi milik OpenClaw.
- **`tool_result_persist`**: secara sinkron mentransformasi hasil alat sebelum ditulis ke transkrip sesi milik OpenClaw.
- **`message_received` / `message_sending` / `message_sent`**: hook pesan masuk + keluar.
- **`session_start` / `session_end`**: batas siklus hidup sesi.
- **`gateway_start` / `gateway_stop`**: peristiwa siklus hidup gateway.
Aturan keputusan hook untuk penjaga keluar/alat:
Aturan keputusan hook untuk guard keluar/alat:
- `before_tool_call`: `{ block: true }` bersifat terminal dan menghentikan handler berprioritas lebih rendah.
- `before_tool_call`: `{ block: false }` adalah no-op dan tidak menghapus blok sebelumnya.
- `before_tool_call`: `{ block: false }` adalah no-op dan tidak menghapus blokir sebelumnya.
- `before_install`: `{ block: true }` bersifat terminal dan menghentikan handler berprioritas lebih rendah.
- `before_install`: `{ block: false }` adalah no-op dan tidak menghapus blok sebelumnya.
- `before_install`: `{ block: false }` adalah no-op dan tidak menghapus blokir sebelumnya.
- `message_sending`: `{ cancel: true }` bersifat terminal dan menghentikan handler berprioritas lebih rendah.
- `message_sending`: `{ cancel: false }` adalah no-op dan tidak menghapus pembatalan sebelumnya.
Lihat [Hook Plugin](/id/plugins/hooks) untuk API hook dan detail pendaftaran.
Harness dapat mengadaptasi hook ini secara berbeda. Harness app-server Codex mempertahankan
hook Plugin OpenClaw sebagai kontrak kompatibilitas untuk surface tercermin yang terdokumentasi,
Harness dapat mengadaptasi hook ini secara berbeda. Harness server aplikasi Codex mempertahankan
hook Plugin OpenClaw sebagai kontrak kompatibilitas untuk permukaan tercermin yang terdokumentasi,
sementara hook native Codex tetap menjadi mekanisme Codex tingkat lebih rendah yang terpisah.
## Streaming + balasan parsial
- Delta asisten di-stream dari pi-agent-core dan dipancarkan sebagai peristiwa `assistant`.
- Delta asisten di-streaming dari pi-agent-core dan dipancarkan sebagai peristiwa `assistant`.
- Streaming blok dapat memancarkan balasan parsial baik pada `text_end` maupun `message_end`.
- Streaming reasoning dapat dipancarkan sebagai stream terpisah atau sebagai balasan blok.
- Streaming penalaran dapat dipancarkan sebagai stream terpisah atau sebagai balasan blok.
- Lihat [Streaming](/id/concepts/streaming) untuk perilaku chunking dan balasan blok.
## Eksekusi alat + alat pesan
## Eksekusi alat + alat perpesanan
- Peristiwa mulai/perbarui/akhir alat dipancarkan pada stream `tool`.
- Hasil alat disanitasi untuk ukuran dan payload gambar sebelum dicatat/dipancarkan.
- Pengiriman alat pesan dilacak untuk menekan konfirmasi asisten duplikat.
- Pengiriman alat perpesanan dilacak untuk menekan konfirmasi asisten yang duplikat.
## Pembentukan balasan + penekanan
## Pembentukan balasan + supresi
- Payload akhir dirakit dari:
- teks asisten (dan reasoning opsional)
- teks asisten (dan penalaran opsional)
- ringkasan alat inline (ketika verbose + diizinkan)
- teks kesalahan asisten ketika model mengalami kesalahan
- Token senyap persis `NO_REPLY` / `no_reply` difilter dari payload
keluar.
- Duplikat alat pesan dihapus dari daftar payload akhir.
- Jika tidak ada payload yang dapat dirender tersisa dan alat mengalami kesalahan, balasan fallback kesalahan alat dipancarkan
(kecuali alat pesan sudah mengirim balasan yang terlihat pengguna).
- Duplikat alat perpesanan dihapus dari daftar payload akhir.
- Jika tidak ada payload yang dapat dirender tersisa dan sebuah alat mengalami kesalahan, balasan kesalahan alat fallback dipancarkan
(kecuali alat perpesanan sudah mengirim balasan yang terlihat oleh pengguna).
## Compaction + percobaan ulang
- Auto-Compaction memancarkan peristiwa stream `compaction` dan dapat memicu percobaan ulang.
- Saat percobaan ulang, buffer dalam memori dan ringkasan alat direset untuk menghindari keluaran duplikat.
- Lihat [Compaction](/id/concepts/compaction) untuk pipeline Compaction.
- Compaction otomatis memancarkan peristiwa stream `compaction` dan dapat memicu percobaan ulang.
- Pada percobaan ulang, buffer dalam memori dan ringkasan alat direset untuk menghindari keluaran duplikat.
- Lihat [Compaction](/id/concepts/compaction) untuk pipeline compaction.
## Stream peristiwa (hari ini)
## Stream peristiwa (saat ini)
- `lifecycle`: dipancarkan oleh `subscribeEmbeddedPiSession` (dan sebagai fallback oleh `agentCommand`)
- `assistant`: delta streaming dari pi-agent-core
@ -162,29 +163,29 @@ sementara hook native Codex tetap menjadi mekanisme Codex tingkat lebih rendah y
## Penanganan kanal chat
- Delta asisten di-buffer ke dalam pesan `delta` chat.
- `final` chat dipancarkan pada **akhir/kesalahan siklus hidup**.
- Delta asisten di-buffer menjadi pesan chat `delta`.
- Chat `final` dipancarkan pada **lifecycle end/error**.
## Timeout
- Default `agent.wait`: 30 dtk (hanya penantian). Parameter `timeoutMs` meng-override.
- Default `agent.wait`: 30 dtk (hanya waktu tunggu). Parameter `timeoutMs` meng-override.
- Runtime agen: default `agents.defaults.timeoutSeconds` 172800 dtk (48 jam); diterapkan di timer batal `runEmbeddedPiAgent`.
- Runtime Cron: `timeoutSeconds` giliran agen terisolasi dimiliki oleh cron. Scheduler memulai timer itu saat eksekusi dimulai, membatalkan eksekusi dasar pada tenggat yang dikonfigurasi, lalu menjalankan pembersihan berbatas sebelum mencatat timeout sehingga sesi anak yang stale tidak dapat membuat jalur macet.
- Pemulihan sesi macet: dengan diagnostik diaktifkan, `diagnostics.stuckSessionWarnMs` mendeteksi sesi `processing` yang lama. Eksekusi tersemat aktif, operasi balasan aktif, dan tugas jalur sesi aktif tetap hanya-peringatan secara default; jika diagnostik menunjukkan tidak ada pekerjaan aktif untuk sesi, watchdog melepaskan jalur sesi terdampak agar pekerjaan startup yang mengantre dapat mengalir.
- Timeout idle model: OpenClaw membatalkan permintaan model ketika tidak ada chunk respons yang tiba sebelum jendela idle. `models.providers.<id>.timeoutSeconds` memperpanjang watchdog idle ini untuk penyedia lokal/self-hosted yang lambat; jika tidak, OpenClaw menggunakan `agents.defaults.timeoutSeconds` ketika dikonfigurasi, dibatasi pada 120 dtk secara default. Eksekusi yang dipicu Cron tanpa timeout model atau agen eksplisit menonaktifkan watchdog idle dan mengandalkan timeout luar cron.
- Timeout permintaan HTTP penyedia: `models.providers.<id>.timeoutSeconds` berlaku untuk fetch HTTP model penyedia tersebut, termasuk connect, header, body, timeout permintaan SDK, penanganan batal guarded-fetch total, dan watchdog idle stream model. Gunakan ini untuk penyedia lokal/self-hosted yang lambat seperti Ollama sebelum menaikkan timeout runtime seluruh agen.
- Runtime Cron: `timeoutSeconds` giliran agen terisolasi dimiliki oleh cron. Scheduler memulai timer tersebut ketika eksekusi dimulai, membatalkan proses jalan dasar pada tenggat yang dikonfigurasi, lalu menjalankan pembersihan berbatas sebelum mencatat timeout sehingga sesi anak yang basi tidak dapat membuat jalur macet.
- Pemulihan sesi macet: dengan diagnostik diaktifkan, `diagnostics.stuckSessionWarnMs` mendeteksi sesi `processing` yang panjang. Proses jalan tertanam aktif, operasi balasan aktif, dan tugas jalur sesi aktif tetap hanya peringatan secara default; jika diagnostik tidak menunjukkan pekerjaan aktif untuk sesi tersebut, watchdog melepaskan jalur sesi yang terdampak agar pekerjaan startup yang mengantre dapat terkuras.
- Timeout idle model: OpenClaw membatalkan permintaan model ketika tidak ada chunk respons yang tiba sebelum jendela idle. `models.providers.<id>.timeoutSeconds` memperpanjang watchdog idle ini untuk penyedia lokal/self-hosted yang lambat; jika tidak, OpenClaw menggunakan `agents.defaults.timeoutSeconds` ketika dikonfigurasi, dibatasi pada 120 dtk secara default. Proses jalan yang dipicu Cron tanpa timeout model atau agen eksplisit menonaktifkan watchdog idle dan mengandalkan timeout luar cron.
- Timeout permintaan HTTP penyedia: `models.providers.<id>.timeoutSeconds` berlaku untuk fetch HTTP model penyedia tersebut, termasuk connect, header, body, timeout permintaan SDK, penanganan abort guarded-fetch total, dan watchdog idle stream model. Gunakan ini untuk penyedia lokal/self-hosted yang lambat seperti Ollama sebelum menaikkan timeout runtime agen secara keseluruhan.
## Tempat hal dapat berakhir lebih awal
- Timeout agen (batal)
- AbortSignal (batal)
- Gateway terputus atau timeout RPC
- Timeout `agent.wait` (hanya penantian, tidak menghentikan agen)
- Putusnya Gateway atau timeout RPC
- Timeout `agent.wait` (hanya menunggu, tidak menghentikan agen)
## Terkait
- [Alat](/id/tools) — alat agen yang tersedia
- [Hook](/id/automation/hooks) — skrip berbasis peristiwa yang dipicu oleh peristiwa siklus hidup agen
- [Compaction](/id/concepts/compaction) — bagaimana percakapan panjang diringkas
- [Compaction](/id/concepts/compaction) — cara percakapan panjang dirangkum
- [Persetujuan Exec](/id/tools/exec-approvals) — gerbang persetujuan untuk perintah shell
- [Thinking](/id/tools/thinking) — konfigurasi tingkat thinking/reasoning
- [Thinking](/id/tools/thinking) — konfigurasi tingkat thinking/penalaran

76
docs/id/concepts/queue.md
View File

@ -5,32 +5,32 @@ read_when:
summary: Mode antrean balasan otomatis, nilai default, dan penggantian per sesi
title: Antrean perintah
x-i18n:
generated_at: "2026-04-30T09:45:45Z"
generated_at: "2026-04-30T18:38:50Z"
model: gpt-5.5
provider: openai
source_hash: 2ac0c0ded9558b080714fa4b8be0d552f985911bf19b427020f9654ae4955b2d
source_hash: fbf1bb1ffd4ce06fa138f63e31651b8821226d9c95dd6b93d68326a5fb91fdd0
source_path: concepts/queue.md
workflow: 16
---
Kami menserialisasi eksekusi auto-reply masuk (semua kanal) melalui antrean kecil dalam proses untuk mencegah beberapa eksekusi agen saling bertabrakan, sambil tetap memungkinkan paralelisme yang aman di seluruh sesi.
Kami menserialkan run balasan otomatis masuk (semua kanal) melalui antrean kecil dalam proses untuk mencegah beberapa run agent bertabrakan, sambil tetap memungkinkan paralelisme aman lintas sesi.
## Mengapa
- Eksekusi auto-reply bisa mahal (panggilan LLM) dan dapat bertabrakan ketika beberapa pesan masuk tiba berdekatan.
- Serialisasi menghindari perebutan sumber daya bersama (file sesi, log, stdin CLI) dan mengurangi kemungkinan terkena batas laju upstream.
- Run balasan otomatis bisa mahal (panggilan LLM) dan bisa bertabrakan ketika beberapa pesan masuk tiba berdekatan.
- Serialisasi menghindari persaingan untuk sumber daya bersama (file sesi, log, stdin CLI) dan mengurangi kemungkinan batas laju upstream.
## Cara kerjanya
- Antrean FIFO yang sadar lajur mengosongkan setiap lajur dengan batas konkurensi yang dapat dikonfigurasi (default 1 untuk lajur yang tidak dikonfigurasi; main default ke 4, subagent ke 8).
- `runEmbeddedPiAgent` mengantrekan berdasarkan **kunci sesi** (lajur `session:<key>`) untuk menjamin hanya ada satu eksekusi aktif per sesi.
- Setiap eksekusi sesi kemudian diantrekan ke **lajur global** (`main` secara default) sehingga paralelisme keseluruhan dibatasi oleh `agents.defaults.maxConcurrent`.
- Ketika logging verbose diaktifkan, eksekusi yang diantrekan mengeluarkan pemberitahuan singkat jika menunggu lebih dari ~2 d sebelum mulai.
- Indikator mengetik tetap aktif segera saat masuk antrean (jika didukung oleh kanal) sehingga pengalaman pengguna tidak berubah saat kita menunggu giliran.
- Antrean FIFO yang sadar lane mengosongkan setiap lane dengan batas konkurensi yang dapat dikonfigurasi (default 1 untuk lane yang tidak dikonfigurasi; main default ke 4, subagent ke 8).
- `runEmbeddedPiAgent` mengantre berdasarkan **kunci sesi** (lane `session:<key>`) untuk menjamin hanya ada satu run aktif per sesi.
- Setiap run sesi kemudian diantrekan ke **lane global** (`main` secara default) sehingga paralelisme keseluruhan dibatasi oleh `agents.defaults.maxConcurrent`.
- Ketika logging verbose diaktifkan, run yang mengantre memancarkan pemberitahuan singkat jika menunggu lebih dari ~2 detik sebelum mulai.
- Indikator mengetik tetap menyala segera saat masuk antrean (ketika didukung oleh kanal) sehingga pengalaman pengguna tidak berubah saat kita menunggu giliran.
## Default
Jika tidak disetel, semua permukaan kanal masuk menggunakan:
Ketika tidak diatur, semua surface kanal masuk menggunakan:
- `mode: "steer"`
- `debounceMs: 500`
@ -38,26 +38,26 @@ Jika tidak disetel, semua permukaan kanal masuk menggunakan:
- `drop: "summarize"`
`steer` adalah default karena menjaga giliran model aktif tetap responsif tanpa
memulai eksekusi sesi kedua. Mode ini mengosongkan semua pesan pengarahan yang tiba
sebelum batas model berikutnya. Jika eksekusi saat ini tidak dapat menerima pengarahan,
OpenClaw beralih ke entri antrean tindak lanjut.
memulai run sesi kedua. Mode ini mengosongkan semua pesan pengarahan yang tiba
sebelum batas model berikutnya. Jika run saat ini tidak dapat menerima pengarahan,
OpenClaw kembali ke entri antrean followup.
## Mode antrean
Pesan masuk dapat mengarahkan eksekusi saat ini, menunggu giliran tindak lanjut, atau melakukan keduanya:
Pesan masuk dapat mengarahkan run saat ini, menunggu giliran followup, atau melakukan keduanya:
- `steer`: antrekan pesan pengarahan ke runtime aktif. Pi mengirimkan semua pesan pengarahan tertunda **setelah giliran asisten saat ini selesai menjalankan pemanggilan tool**, sebelum panggilan LLM berikutnya; Codex app-server menerima satu `turn/steer` yang dibatch. Jika eksekusi tidak aktif melakukan streaming atau pengarahan tidak tersedia, OpenClaw beralih ke entri antrean tindak lanjut.
- `queue` (legacy): pengarahan satu per satu yang lama. Pi mengirimkan satu pesan pengarahan yang diantrekan pada setiap batas model; Codex app-server menerima permintaan `turn/steer` terpisah. Utamakan `steer` kecuali Anda memerlukan perilaku serial sebelumnya.
- `followup`: antrekan setiap pesan untuk giliran agen berikutnya setelah eksekusi saat ini berakhir.
- `collect`: gabungkan pesan yang diantrekan menjadi giliran tindak lanjut **tunggal** setelah jendela hening. Jika pesan menargetkan kanal/thread yang berbeda, pesan dikosongkan secara individual untuk mempertahankan routing.
- `steer-backlog` (alias `steer+backlog`): arahkan sekarang **dan** pertahankan pesan yang sama untuk giliran tindak lanjut.
- `interrupt` (legacy): batalkan eksekusi aktif untuk sesi tersebut, lalu jalankan pesan terbaru.
- `steer`: antrekan pesan pengarahan ke runtime aktif. Pi mengirim semua pesan pengarahan tertunda **setelah giliran asisten saat ini selesai menjalankan panggilan tool-nya**, sebelum panggilan LLM berikutnya; Codex app-server menerima satu `turn/steer` yang dibatch. Jika run tidak aktif streaming atau pengarahan tidak tersedia, OpenClaw kembali ke entri antrean followup.
- `queue` (lama): pengarahan lama satu per satu. Pi mengirim satu pesan pengarahan yang diantrekan pada setiap batas model; Codex app-server menerima permintaan `turn/steer` terpisah. Lebih pilih `steer` kecuali Anda memerlukan perilaku terserialisasi sebelumnya.
- `followup`: antrekan setiap pesan untuk giliran agent berikutnya setelah run saat ini berakhir.
- `collect`: gabungkan pesan yang diantrekan menjadi giliran followup **tunggal** setelah jendela hening. Jika pesan menargetkan kanal/thread berbeda, pesan dikosongkan satu per satu untuk mempertahankan routing.
- `steer-backlog` (alias `steer+backlog`): arahkan sekarang **dan** pertahankan pesan yang sama untuk giliran followup.
- `interrupt` (lama): batalkan run aktif untuk sesi tersebut, lalu jalankan pesan terbaru.
Steer-backlog berarti Anda bisa mendapatkan respons tindak lanjut setelah eksekusi yang diarahkan, sehingga
permukaan streaming dapat terlihat seperti duplikat. Utamakan `collect`/`steer` jika Anda menginginkan
Steer-backlog berarti Anda bisa mendapatkan respons followup setelah run yang diarahkan, sehingga
surface streaming dapat terlihat seperti duplikat. Lebih pilih `collect`/`steer` jika Anda menginginkan
satu respons per pesan masuk.
Untuk perilaku timing dan dependensi khusus runtime, lihat
Untuk timing spesifik runtime dan perilaku dependensi, lihat
[Antrean pengarahan](/id/concepts/queue-steering).
Konfigurasikan secara global atau per kanal melalui `messages.queue`:
@ -78,12 +78,12 @@ Konfigurasikan secara global atau per kanal melalui `messages.queue`:
## Opsi antrean
Opsi berlaku untuk `followup`, `collect`, dan `steer-backlog` (serta untuk `steer` atau `queue` legacy ketika pengarahan beralih ke tindak lanjut):
Opsi berlaku untuk `followup`, `collect`, dan `steer-backlog` (serta untuk `steer` atau `queue` lama ketika pengarahan kembali ke followup):
- `debounceMs`: jendela hening sebelum mengosongkan tindak lanjut yang diantrekan. Angka polos adalah milidetik; satuan `ms`, `s`, `m`, `h`, dan `d` diterima oleh opsi `/queue`.
- `debounceMs`: jendela hening sebelum mengosongkan followup yang diantrekan. Angka polos adalah milidetik; satuan `ms`, `s`, `m`, `h`, dan `d` diterima oleh opsi `/queue`.
- `cap`: jumlah maksimum pesan yang diantrekan per sesi. Nilai di bawah `1` diabaikan.
- `drop: "summarize"`: default. Hapus entri antrean terlama sesuai kebutuhan, simpan ringkasan ringkas, dan injeksikan sebagai prompt tindak lanjut sintetis.
- `drop: "old"`: hapus entri antrean terlama sesuai kebutuhan, tanpa mempertahankan ringkasan.
- `drop: "summarize"`: default. Jatuhkan entri antrean tertua sesuai kebutuhan, simpan ringkasan padat, dan sisipkan sebagai prompt followup sintetis.
- `drop: "old"`: jatuhkan entri antrean tertua sesuai kebutuhan, tanpa mempertahankan ringkasan.
- `drop: "new"`: tolak pesan terbaru ketika antrean sudah penuh.
Default: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
@ -92,16 +92,15 @@ Default: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
Untuk pemilihan mode, OpenClaw menyelesaikan:
1. Override `/queue` inline atau tersimpan per sesi.
1. Override `/queue` per sesi inline atau tersimpan.
2. `messages.queue.byChannel.<channel>`.
3. `messages.queue.mode`.
4. Default `steer`.
Untuk opsi, opsi `/queue` inline atau tersimpan menang atas konfigurasi. Lalu
debounce khusus kanal (`messages.queue.debounceMsByChannel`), default debounce
Plugin, opsi global `messages.queue`, dan default bawaan
diterapkan. `cap` dan `drop` adalah opsi global/sesi, bukan kunci konfigurasi
per kanal.
Plugin, opsi global `messages.queue`, dan default bawaan diterapkan. `cap` dan
`drop` adalah opsi global/sesi, bukan kunci konfigurasi per kanal.
## Override per sesi
@ -111,17 +110,18 @@ per kanal.
## Cakupan dan jaminan
- Berlaku untuk eksekusi agen auto-reply di semua kanal masuk yang menggunakan pipeline balasan gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, dll.).
- Lajur default (`main`) berlaku di seluruh proses untuk inbound + heartbeat utama; setel `agents.defaults.maxConcurrent` untuk mengizinkan beberapa sesi berjalan paralel.
- Lajur tambahan mungkin ada (mis. `cron`, `cron-nested`, `nested`, `subagent`) sehingga job latar belakang dapat berjalan paralel tanpa memblokir balasan masuk. Giliran agen cron terisolasi menahan slot `cron` sementara eksekusi agen dalamnya menggunakan `cron-nested`; keduanya menggunakan `cron.maxConcurrentRuns`. Alur `nested` non-cron bersama mempertahankan perilaku lajurnya sendiri. Eksekusi terlepas ini dilacak sebagai [tugas latar belakang](/id/automation/tasks).
- Lajur per sesi menjamin bahwa hanya satu eksekusi agen menyentuh sesi tertentu pada satu waktu.
- Tanpa dependensi eksternal atau thread worker latar belakang; TypeScript + promise murni.
- Berlaku untuk run agent balasan otomatis di semua kanal masuk yang menggunakan pipeline balasan Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, dll.).
- Lane default (`main`) berlaku di seluruh proses untuk inbound + Heartbeat utama; atur `agents.defaults.maxConcurrent` untuk mengizinkan beberapa sesi berjalan paralel.
- Lane tambahan mungkin ada (mis. `cron`, `cron-nested`, `nested`, `subagent`) sehingga pekerjaan latar belakang dapat berjalan paralel tanpa memblokir balasan masuk. Giliran agent Cron terisolasi memegang slot `cron` sementara eksekusi agent bagian dalamnya menggunakan `cron-nested`; keduanya menggunakan `cron.maxConcurrentRuns`. Alur `nested` non-cron bersama mempertahankan perilaku lane masing-masing. Run terlepas ini dilacak sebagai [tugas latar belakang](/id/automation/tasks).
- Lane per sesi menjamin bahwa hanya satu run agent menyentuh sesi tertentu pada satu waktu.
- Tanpa dependensi eksternal atau thread worker latar belakang; TypeScript murni + promise.
## Pemecahan masalah
- Jika perintah tampak macet, aktifkan log verbose dan cari baris “queued for …ms” untuk memastikan antrean sedang dikosongkan.
- Jika Anda memerlukan kedalaman antrean, aktifkan log verbose dan pantau baris timing antrean.
- Ketika diagnostik diaktifkan, sesi yang tetap berada di `processing` melewati `diagnostics.stuckSessionWarnMs` mencatat peringatan sesi macet. Eksekusi embedded aktif, operasi balasan aktif, dan tugas lajur aktif tetap hanya berupa peringatan secara default; pembukuan startup yang basi tanpa pekerjaan sesi aktif dapat melepas lajur sesi terdampak sehingga pekerjaan yang diantrekan dikosongkan.
- Run Codex app-server yang menerima sebuah giliran lalu berhenti memancarkan progres diinterupsi oleh adapter Codex sehingga lane sesi aktif dapat dilepas alih-alih menunggu timeout run luar.
- Ketika diagnostik diaktifkan, sesi yang tetap berada dalam `processing` melewati `diagnostics.stuckSessionWarnMs` mencatat peringatan sesi macet. Run embedded aktif, operasi balasan aktif, dan tugas lane aktif tetap hanya berupa peringatan secara default; bookkeeping startup yang stale tanpa pekerjaan sesi aktif dapat melepas lane sesi yang terpengaruh sehingga pekerjaan yang diantrekan dapat dikosongkan.
## Terkait

755
docs/id/help/testing.md
View File

File diff suppressed because it is too large Load Diff

89
docs/id/reference/test.md
View File

@ -4,55 +4,56 @@ read_when:
summary: Cara menjalankan pengujian secara lokal (vitest) dan kapan menggunakan mode force/coverage
title: Pengujian
x-i18n:
generated_at: "2026-04-30T10:11:15Z"
generated_at: "2026-04-30T18:38:40Z"
model: gpt-5.5
provider: openai
source_hash: 9328d6f0383b5067fa8bb5d0f1bf22a3b9048a267908bf85167842ddc3d12e42
source_hash: 131f2bad3b2806d28394213cec38d632d106ddbf8ff04d06345ab8046fb8bcf2
source_path: reference/test.md
workflow: 16
---
- Kit pengujian lengkap (suite, langsung, Docker): [Pengujian](/id/help/testing)
- Kit pengujian lengkap (rangkaian pengujian, pengujian langsung, Docker): [Pengujian](/id/help/testing)
- `pnpm test:force`: Mematikan proses gateway tersisa yang menahan port kontrol default, lalu menjalankan rangkaian lengkap Vitest dengan port Gateway terisolasi agar pengujian server tidak bertabrakan dengan instance yang sedang berjalan. Gunakan ini ketika proses Gateway sebelumnya membuat port 18789 tetap terpakai.
- `pnpm test:coverage`: Menjalankan rangkaian unit dengan cakupan V8 (melalui `vitest.unit.config.ts`). Ini adalah gate cakupan unit untuk file yang dimuat, bukan cakupan semua file seluruh repo. Ambangnya adalah 70% baris/fungsi/pernyataan dan 55% cabang. Karena `coverage.all` bernilai false, gate ini mengukur file yang dimuat oleh rangkaian cakupan unit, bukan memperlakukan setiap file sumber split-lane sebagai tidak tercakup.
- `pnpm test:force`: Menghentikan paksa proses Gateway yang masih tersisa dan menahan port kontrol default, lalu menjalankan seluruh rangkaian Vitest dengan port Gateway terisolasi agar pengujian server tidak bertabrakan dengan instans yang sedang berjalan. Gunakan ini ketika proses Gateway sebelumnya membuat port 18789 tetap terpakai.
- `pnpm test:coverage`: Menjalankan rangkaian unit dengan cakupan V8 (melalui `vitest.unit.config.ts`). Ini adalah gate cakupan unit untuk file yang dimuat, bukan cakupan semua file seluruh repo. Ambangnya adalah 70% untuk baris/fungsi/pernyataan dan 55% untuk cabang. Karena `coverage.all` bernilai false, gate ini mengukur file yang dimuat oleh rangkaian cakupan unit, alih-alih memperlakukan setiap file sumber split-lane sebagai tidak tercakup.
- `pnpm test:coverage:changed`: Menjalankan cakupan unit hanya untuk file yang berubah sejak `origin/main`.
- `pnpm test:changed`: proses pengujian perubahan pintar yang murah. Ini menjalankan target presisi dari pengeditan pengujian langsung, file sibling `*.test.ts`, pemetaan sumber eksplisit, dan grafik impor lokal. Perubahan luas/config/package dilewati kecuali dipetakan ke pengujian presisi.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: proses pengujian perubahan luas eksplisit. Gunakan ketika pengeditan harness/config/package pengujian harus kembali ke perilaku changed-test Vitest yang lebih luas.
- `pnpm test:changed`: proses pengujian perubahan cerdas yang murah. Ini menjalankan target presisi dari edit pengujian langsung, file sibling `*.test.ts`, pemetaan sumber eksplisit, dan grafik impor lokal. Perubahan luas/konfigurasi/paket dilewati kecuali dipetakan ke pengujian yang presisi.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: proses pengujian perubahan luas eksplisit. Gunakan ini ketika edit harness/konfigurasi/paket pengujian harus kembali ke perilaku pengujian perubahan Vitest yang lebih luas.
- `pnpm changed:lanes`: menampilkan lane arsitektural yang dipicu oleh diff terhadap `origin/main`.
- `pnpm check:changed`: menjalankan gate pemeriksaan perubahan pintar untuk diff terhadap `origin/main`. Ini menjalankan typecheck, lint, dan perintah guard untuk lane arsitektural yang terdampak, tetapi tidak menjalankan pengujian Vitest. Gunakan `pnpm test:changed` atau `pnpm test <target>` eksplisit untuk bukti pengujian.
- `pnpm test`: merutekan target file/direktori eksplisit melalui lane Vitest terskop. Proses tanpa target menggunakan grup shard tetap dan memperluas ke config leaf untuk eksekusi paralel lokal; grup ekstensi selalu diperluas ke config shard per ekstensi, bukan satu proses root-project raksasa.
- Proses wrapper pengujian diakhiri dengan ringkasan singkat `[test] passed|failed|skipped ... in ...`. Baris durasi bawaan Vitest tetap menjadi detail per-shard.
- State pengujian OpenClaw bersama: gunakan `src/test-utils/openclaw-test-state.ts` dari Vitest ketika pengujian membutuhkan `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture config, workspace, direktori agent, atau penyimpanan auth-profile yang terisolasi.
- Helper E2E proses: gunakan `test/helpers/openclaw-test-instance.ts` ketika pengujian E2E tingkat proses Vitest membutuhkan Gateway berjalan, env CLI, penangkapan log, dan pembersihan di satu tempat.
- Helper E2E Docker/Bash: lane yang melakukan source `scripts/lib/docker-e2e-image.sh` dapat meneruskan `docker_e2e_test_state_shell_b64 <label> <scenario>` ke dalam container dan mendekodenya dengan `scripts/lib/openclaw-e2e-instance.sh`; skrip multi-home dapat meneruskan `docker_e2e_test_state_function_b64` dan memanggil `openclaw_test_state_create <label> <scenario>` di setiap flow. Pemanggil tingkat lebih rendah dapat menggunakan `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` untuk snippet shell di dalam container, atau `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` untuk file env host yang dapat di-source. `--` sebelum `create` mencegah runtime Node yang lebih baru memperlakukan `--env-file` sebagai flag Node. Lane Docker/Bash yang meluncurkan Gateway dapat melakukan source `scripts/lib/openclaw-e2e-instance.sh` di dalam container untuk resolusi entrypoint, startup OpenAI tiruan, peluncuran Gateway foreground/background, probe kesiapan, ekspor env state, dump log, dan pembersihan proses.
- Proses shard lengkap, ekstensi, dan include-pattern memperbarui data timing lokal di `.artifacts/vitest-shard-timings.json`; proses whole-config berikutnya menggunakan timing tersebut untuk menyeimbangkan shard lambat dan cepat. Shard CI include-pattern menambahkan nama shard ke kunci timing, yang menjaga timing shard terfilter tetap terlihat tanpa mengganti data timing whole-config. Atur `OPENCLAW_TEST_PROJECTS_TIMINGS=0` untuk mengabaikan artefak timing lokal.
- File pengujian `plugin-sdk` dan `commands` terpilih kini dirutekan melalui lane ringan khusus yang hanya mempertahankan `test/setup.ts`, membiarkan kasus runtime-heavy tetap di lane yang sudah ada.
- File sumber dengan pengujian sibling dipetakan ke sibling tersebut sebelum fallback ke glob direktori yang lebih luas. Pengeditan helper di bawah `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, dan `src/plugins/contracts` menggunakan grafik impor lokal untuk menjalankan pengujian yang mengimpor, bukan menjalankan luas setiap shard ketika path dependensi presisi.
- `auto-reply` kini juga dibagi menjadi tiga config khusus (`core`, `top-level`, `reply`) sehingga harness balasan tidak mendominasi pengujian status/token/helper top-level yang lebih ringan.
- Config dasar Vitest kini default ke `pool: "threads"` dan `isolate: false`, dengan runner non-terisolasi bersama diaktifkan di seluruh config repo.
- `pnpm check:changed`: menjalankan gate pemeriksaan perubahan cerdas untuk diff terhadap `origin/main`. Ini menjalankan typecheck, lint, dan perintah guard untuk lane arsitektural yang terdampak, tetapi tidak menjalankan pengujian Vitest. Gunakan `pnpm test:changed` atau `pnpm test <target>` eksplisit untuk bukti pengujian.
- `pnpm test`: merutekan target file/direktori eksplisit melalui lane Vitest berskop. Proses tanpa target memakai grup shard tetap dan mengembang ke konfigurasi leaf untuk eksekusi paralel lokal; grup ekstensi selalu mengembang ke konfigurasi shard per-ekstensi, bukan satu proses root-project raksasa.
- Proses wrapper pengujian berakhir dengan ringkasan singkat `[test] passed|failed|skipped ... in ...`. Baris durasi milik Vitest tetap menjadi detail per-shard.
- Status pengujian OpenClaw bersama: gunakan `src/test-utils/openclaw-test-state.ts` dari Vitest ketika sebuah pengujian memerlukan `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture konfigurasi, workspace, direktori agen, atau penyimpanan auth-profile yang terisolasi.
- Helper E2E proses: gunakan `test/helpers/openclaw-test-instance.ts` ketika pengujian E2E level proses Vitest memerlukan Gateway yang berjalan, env CLI, pengambilan log, dan pembersihan di satu tempat.
- Helper E2E Docker/Bash: lane yang melakukan source `scripts/lib/docker-e2e-image.sh` dapat meneruskan `docker_e2e_test_state_shell_b64 <label> <scenario>` ke dalam kontainer dan mendekodenya dengan `scripts/lib/openclaw-e2e-instance.sh`; skrip multi-home dapat meneruskan `docker_e2e_test_state_function_b64` dan memanggil `openclaw_test_state_create <label> <scenario>` di setiap alur. Pemanggil level lebih rendah dapat menggunakan `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` untuk cuplikan shell di dalam kontainer, atau `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` untuk file env host yang dapat di-source. `--` sebelum `create` mencegah runtime Node yang lebih baru memperlakukan `--env-file` sebagai flag Node. Lane Docker/Bash yang meluncurkan Gateway dapat melakukan source `scripts/lib/openclaw-e2e-instance.sh` di dalam kontainer untuk resolusi entrypoint, startup OpenAI tiruan, peluncuran Gateway foreground/background, probe kesiapan, ekspor env status, dump log, dan pembersihan proses.
- Proses shard penuh, ekstensi, dan include-pattern memperbarui data timing lokal di `.artifacts/vitest-shard-timings.json`; proses whole-config berikutnya memakai timing tersebut untuk menyeimbangkan shard lambat dan cepat. Shard CI include-pattern menambahkan nama shard ke kunci timing, sehingga timing shard terfilter tetap terlihat tanpa mengganti data timing whole-config. Setel `OPENCLAW_TEST_PROJECTS_TIMINGS=0` untuk mengabaikan artefak timing lokal.
- File pengujian `plugin-sdk` dan `commands` terpilih sekarang dirutekan melalui lane ringan khusus yang hanya mempertahankan `test/setup.ts`, sementara kasus runtime-heavy tetap di lane yang sudah ada.
- File sumber dengan pengujian sibling dipetakan ke sibling tersebut sebelum fallback ke glob direktori yang lebih luas. Edit helper di bawah `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, dan `src/plugins/contracts` memakai grafik impor lokal untuk menjalankan pengujian yang mengimpor, alih-alih menjalankan luas setiap shard ketika jalur dependensinya presisi.
- `auto-reply` sekarang juga dipisah menjadi tiga konfigurasi khusus (`core`, `top-level`, `reply`) sehingga harness reply tidak mendominasi pengujian status/token/helper top-level yang lebih ringan.
- Konfigurasi dasar Vitest sekarang default ke `pool: "threads"` dan `isolate: false`, dengan runner non-terisolasi bersama diaktifkan di seluruh konfigurasi repo.
- `pnpm test:channels` menjalankan `vitest.channels.config.ts`.
- `pnpm test:extensions` dan `pnpm test extensions` menjalankan semua shard ekstensi/plugin. Plugin channel berat, Plugin browser, dan OpenAI berjalan sebagai shard khusus; grup plugin lain tetap dibatch. Gunakan `pnpm test extensions/<id>` untuk satu lane plugin bawaan.
- `pnpm test:perf:imports`: mengaktifkan pelaporan durasi impor + rincian impor Vitest, sembari tetap menggunakan perutean lane terskop untuk target file/direktori eksplisit.
- `pnpm test:extensions` dan `pnpm test extensions` menjalankan semua shard ekstensi/plugin. Plugin channel berat, Plugin browser, dan OpenAI berjalan sebagai shard khusus; grup Plugin lainnya tetap dibatch. Gunakan `pnpm test extensions/<id>` untuk satu lane Plugin bawaan.
- `pnpm test:perf:imports`: mengaktifkan pelaporan durasi impor + rincian impor Vitest, sambil tetap memakai perutean lane berskop untuk target file/direktori eksplisit.
- `pnpm test:perf:imports:changed`: profiling impor yang sama, tetapi hanya untuk file yang berubah sejak `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` membenchmark path changed-mode yang dirutekan terhadap proses root-project native untuk diff git committed yang sama.
- `pnpm test:perf:changed:bench -- --worktree` membenchmark set perubahan worktree saat ini tanpa commit terlebih dahulu.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` melakukan benchmark jalur changed-mode yang dirutekan terhadap proses root-project native untuk diff git commit yang sama.
- `pnpm test:perf:changed:bench -- --worktree` melakukan benchmark kumpulan perubahan worktree saat ini tanpa perlu commit terlebih dahulu.
- `pnpm test:perf:profile:main`: menulis profil CPU untuk thread utama Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: menulis profil CPU + heap untuk runner unit (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: menjalankan setiap config leaf Vitest full-suite secara serial dan menulis data durasi tergroup beserta artefak JSON/log per-config. Test Performance Agent menggunakan ini sebagai baseline sebelum mencoba perbaikan pengujian lambat.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: membandingkan laporan tergroup setelah perubahan yang berfokus pada performa.
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: menjalankan setiap konfigurasi leaf Vitest full-suite secara serial dan menulis data durasi berkelompok plus artefak JSON/log per-konfigurasi. Test Performance Agent menggunakan ini sebagai baseline sebelum mencoba perbaikan pengujian lambat.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: membandingkan laporan berkelompok setelah perubahan yang berfokus pada performa.
- Integrasi Gateway: ikut serta melalui `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` atau `pnpm test:gateway`.
- `pnpm test:e2e`: Menjalankan pengujian smoke end-to-end Gateway (pairing multi-instance WS/HTTP/node). Default ke `threads` + `isolate: false` dengan worker adaptif di `vitest.e2e.config.ts`; sesuaikan dengan `OPENCLAW_E2E_WORKERS=<n>` dan atur `OPENCLAW_E2E_VERBOSE=1` untuk log verbose.
- `pnpm test:live`: Menjalankan pengujian live provider (minimax/zai). Membutuhkan kunci API dan `LIVE=1` (atau `*_LIVE_TEST=1` khusus provider) agar tidak dilewati.
- `pnpm test:docker:all`: Membangun image live-test bersama, mengemas OpenClaw sekali sebagai tarball npm, membangun/menggunakan ulang image runner Node/Git kosong serta image fungsional yang menginstal tarball tersebut ke `/app`, lalu menjalankan lane smoke Docker dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` melalui scheduler berbobot. Image kosong (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) digunakan untuk lane installer/update/plugin-dependency; lane tersebut memasang tarball prabangun, bukan menggunakan sumber repo yang disalin. Image fungsional (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) digunakan untuk lane fungsionalitas built-app normal. `scripts/package-openclaw-for-docker.mjs` adalah satu-satunya packer package lokal/CI dan memvalidasi tarball serta `dist/postinstall-inventory.json` sebelum Docker mengonsumsinya. Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`; logika planner berada di `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` mengeksekusi rencana terpilih. `node scripts/test-docker-all.mjs --plan-json` menghasilkan rencana CI milik scheduler untuk lane terpilih, jenis image, kebutuhan package/live-image, skenario state, dan pemeriksaan kredensial tanpa membangun atau menjalankan Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` mengontrol slot proses dan default ke 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` mengontrol pool tail yang sensitif terhadap provider dan default ke 10. Batas lane berat default ke `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, dan `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; batas provider default ke satu lane berat per provider melalui `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4`, dan `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Gunakan `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` atau `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` untuk host yang lebih besar. Jika satu lane melebihi batas bobot atau sumber daya efektif pada host dengan paralelisme rendah, lane tersebut tetap dapat mulai dari pool kosong dan akan berjalan sendiri hingga melepas kapasitas. Start lane diberi jeda 2 detik secara default untuk menghindari lonjakan create daemon Docker lokal; override dengan `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner melakukan preflight Docker secara default, membersihkan container E2E OpenClaw stale, memancarkan status active-lane setiap 30 detik, berbagi cache tool CLI provider antar lane yang kompatibel, mencoba ulang kegagalan transient live-provider sekali secara default (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`), dan menyimpan timing lane di `.artifacts/docker-tests/lane-timings.json` untuk pengurutan longest-first pada proses berikutnya. Gunakan `OPENCLAW_DOCKER_ALL_DRY_RUN=1` untuk mencetak manifest lane tanpa menjalankan Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` untuk menyesuaikan output status, atau `OPENCLAW_DOCKER_ALL_TIMINGS=0` untuk menonaktifkan penggunaan ulang timing. Gunakan `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` hanya untuk lane deterministik/lokal atau `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` hanya untuk lane live-provider; alias package adalah `pnpm test:docker:local:all` dan `pnpm test:docker:live:all`. Mode live-only menggabungkan lane live main dan tail menjadi satu pool longest-first sehingga bucket provider dapat mengemas pekerjaan Claude, Codex, dan Gemini bersama-sama. Runner berhenti menjadwalkan lane pooled baru setelah kegagalan pertama kecuali `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` diatur, dan setiap lane memiliki timeout fallback 120 menit yang dapat dioverride dengan `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lane live/tail terpilih menggunakan batas per-lane yang lebih ketat. Perintah penyiapan Docker backend CLI memiliki timeout sendiri melalui `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (default 180). Log per-lane, `summary.json`, `failures.json`, dan timing fase ditulis di bawah `.artifacts/docker-tests/<run-id>/`; gunakan `pnpm test:docker:timings <summary.json>` untuk memeriksa lane lambat dan `pnpm test:docker:rerun <run-id|summary.json|failures.json>` untuk mencetak perintah rerun tertarget yang murah.
- `pnpm test:docker:browser-cdp-snapshot`: Membangun container E2E sumber berbasis Chromium, memulai CDP mentah plus Gateway terisolasi, menjalankan `browser doctor --deep`, dan memverifikasi snapshot peran CDP menyertakan URL tautan, clickable yang dipromosikan kursor, ref iframe, dan metadata frame.
- `pnpm test:e2e`: Menjalankan pengujian smoke end-to-end Gateway (pairing multi-instans WS/HTTP/node). Default ke `threads` + `isolate: false` dengan worker adaptif di `vitest.e2e.config.ts`; sesuaikan dengan `OPENCLAW_E2E_WORKERS=<n>` dan setel `OPENCLAW_E2E_VERBOSE=1` untuk log verbose.
- `pnpm test:live`: Menjalankan pengujian live provider (minimax/zai). Memerlukan API key dan `LIVE=1` (atau `*_LIVE_TEST=1` khusus provider) agar tidak diskip.
- `pnpm test:docker:all`: Membangun image live-test bersama, mengemas OpenClaw sekali sebagai tarball npm, membangun/memakai ulang image runner Node/Git bare plus image fungsional yang memasang tarball itu ke `/app`, lalu menjalankan lane smoke Docker dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` melalui scheduler berbobot. Image bare (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) digunakan untuk lane installer/update/dependensi-plugin; lane tersebut me-mount tarball prabangun alih-alih memakai sumber repo yang disalin. Image fungsional (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) digunakan untuk lane fungsionalitas built-app normal. `scripts/package-openclaw-for-docker.mjs` adalah satu-satunya packer paket lokal/CI dan memvalidasi tarball plus `dist/postinstall-inventory.json` sebelum Docker mengonsumsinya. Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`; logika planner berada di `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` mengeksekusi plan terpilih. `node scripts/test-docker-all.mjs --plan-json` memancarkan plan CI milik scheduler untuk lane terpilih, jenis image, kebutuhan paket/live-image, skenario status, dan pemeriksaan kredensial tanpa membangun atau menjalankan Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` mengontrol slot proses dan default ke 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` mengontrol pool tail yang sensitif provider dan default ke 10. Batas lane berat default ke `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, dan `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; batas provider default ke satu lane berat per provider melalui `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4`, dan `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Gunakan `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` atau `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` untuk host yang lebih besar. Jika satu lane melampaui batas bobot atau sumber daya efektif pada host dengan paralelisme rendah, lane itu tetap dapat dimulai dari pool kosong dan akan berjalan sendiri sampai melepas kapasitas. Awal lane diberi jeda 2 detik secara default untuk menghindari lonjakan pembuatan daemon Docker lokal; ubah dengan `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner melakukan preflight Docker secara default, membersihkan kontainer E2E OpenClaw yang usang, memancarkan status active-lane setiap 30 detik, membagikan cache tool CLI provider antar-lane yang kompatibel, mencoba ulang kegagalan live-provider sementara sekali secara default (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`), dan menyimpan timing lane di `.artifacts/docker-tests/lane-timings.json` untuk pengurutan terpanjang-dulu pada proses berikutnya. Gunakan `OPENCLAW_DOCKER_ALL_DRY_RUN=1` untuk mencetak manifes lane tanpa menjalankan Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` untuk menyesuaikan output status, atau `OPENCLAW_DOCKER_ALL_TIMINGS=0` untuk menonaktifkan penggunaan ulang timing. Gunakan `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` hanya untuk lane deterministik/lokal atau `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` hanya untuk lane live-provider; alias paketnya adalah `pnpm test:docker:local:all` dan `pnpm test:docker:live:all`. Mode live-only menggabungkan lane live utama dan tail ke satu pool terpanjang-dulu sehingga bucket provider dapat mengemas pekerjaan Claude, Codex, dan Gemini bersama. Runner berhenti menjadwalkan lane pooled baru setelah kegagalan pertama kecuali `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` disetel, dan setiap lane memiliki timeout fallback 120 menit yang dapat diubah dengan `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lane live/tail terpilih memakai batas per-lane yang lebih ketat. Perintah setup Docker backend CLI memiliki timeout sendiri melalui `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (default 180). Log per-lane, `summary.json`, `failures.json`, dan timing fase ditulis di bawah `.artifacts/docker-tests/<run-id>/`; gunakan `pnpm test:docker:timings <summary.json>` untuk memeriksa lane lambat dan `pnpm test:docker:rerun <run-id|summary.json|failures.json>` untuk mencetak perintah rerun tertarget yang murah.
- `pnpm test:docker:browser-cdp-snapshot`: Membangun kontainer E2E sumber berbasis Chromium, memulai CDP mentah plus Gateway terisolasi, menjalankan `browser doctor --deep`, dan memverifikasi snapshot peran CDP menyertakan URL tautan, clickable yang dipromosikan kursor, ref iframe, dan metadata frame.
- Probe Docker live backend CLI dapat dijalankan sebagai lane terfokus, misalnya `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume`, atau `pnpm test:docker:live-cli-backend:codex:mcp`. Claude dan Gemini memiliki alias `:resume` dan `:mcp` yang sesuai.
- `pnpm test:docker:openwebui`: Memulai OpenClaw + Open WebUI dalam Docker, masuk melalui Open WebUI, memeriksa `/api/models`, lalu menjalankan chat terproksi nyata melalui `/api/chat/completions`. Membutuhkan kunci model live yang dapat digunakan (misalnya OpenAI di `~/.profile`), menarik image Open WebUI eksternal, dan tidak diharapkan stabil di CI seperti rangkaian unit/e2e normal.
- `pnpm test:docker:mcp-channels`: Memulai container Gateway yang sudah diseed dan container klien kedua yang menjalankan `openclaw mcp serve`, lalu memverifikasi penemuan percakapan terutekan, pembacaan transkrip, metadata lampiran, perilaku antrean event live, perutean pengiriman outbound, dan notifikasi channel + izin bergaya Claude melalui bridge stdio nyata. Assertion notifikasi Claude membaca frame MCP stdio mentah secara langsung sehingga smoke mencerminkan apa yang benar-benar dipancarkan bridge.
- `pnpm test:docker:openwebui`: Memulai OpenClaw + Open WebUI dalam Docker, masuk melalui Open WebUI, memeriksa `/api/models`, lalu menjalankan chat proksi nyata melalui `/api/chat/completions`. Memerlukan key model live yang dapat digunakan (misalnya OpenAI di `~/.profile`), menarik image Open WebUI eksternal, dan tidak diharapkan stabil di CI seperti rangkaian unit/e2e normal.
- `pnpm test:docker:mcp-channels`: Memulai kontainer Gateway ber-seed dan kontainer klien kedua yang menjalankan `openclaw mcp serve`, lalu memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata lampiran, perilaku antrean event live, perutean kirim outbound, dan notifikasi channel + izin gaya Claude melalui bridge stdio nyata. Assertion notifikasi Claude membaca frame MCP stdio mentah secara langsung sehingga smoke mencerminkan apa yang benar-benar dipancarkan bridge.
- `pnpm test:docker:upgrade-survivor`: Menginstal tarball OpenClaw yang sudah dikemas di atas fixture pengguna lama yang kotor, menjalankan pembaruan paket serta doctor noninteraktif tanpa provider live atau kunci channel, lalu memulai Gateway loopback dan memeriksa bahwa agent, konfigurasi channel, daftar izin plugin, file workspace/sesi, status stale plugin runtime-deps, startup, dan status RPC tetap bertahan.
## Gate PR lokal
## Gerbang PR lokal
Untuk pemeriksaan land/gate PR lokal, jalankan:
Untuk pemeriksaan penggabungan/gerbang PR lokal, jalankan:
- `pnpm check:changed`
- `pnpm check`
@ -61,7 +62,7 @@ Untuk pemeriksaan land/gate PR lokal, jalankan:
- `pnpm test`
- `pnpm check:docs`
Jika `pnpm test` gagal sesekali pada host yang sedang terbebani, jalankan ulang sekali sebelum menganggapnya sebagai regresi, lalu isolasi dengan `pnpm test <path/to/test>`. Untuk host dengan memori terbatas, gunakan:
Jika `pnpm test` gagal tidak stabil pada mesin yang terbebani, jalankan ulang satu kali sebelum memperlakukannya sebagai regresi, lalu isolasi dengan `pnpm test <path/to/test>`. Untuk mesin dengan memori terbatas, gunakan:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -74,9 +75,9 @@ Penggunaan:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Env opsional: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt default: “Balas dengan satu kata: ok. Tanpa tanda baca atau teks tambahan.”
- Prompt bawaan: “Balas dengan satu kata: ok. Tanpa tanda baca atau teks tambahan.”
Jalankan terakhir (2025-12-31, 20 kali):
Jalankan terakhir (2025-12-31, 20 kali jalan):
- median minimax 1279ms (min 1114, maks 2431)
- median opus 2454ms (min 1224, maks 3170)
@ -109,15 +110,15 @@ Preset:
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: kedua preset
Output mencakup `sampleCount`, rata-rata, p50, p95, min/maks, distribusi exit-code/sinyal, dan ringkasan RSS maksimum untuk setiap perintah. `--cpu-prof-dir` / `--heap-prof-dir` opsional menulis profil V8 per proses jalan sehingga waktu dan pengambilan profil memakai harness yang sama.
Output mencakup `sampleCount`, rata-rata, p50, p95, min/maks, distribusi exit-code/sinyal, dan ringkasan RSS maksimum untuk setiap perintah. `--cpu-prof-dir` / `--heap-prof-dir` opsional menulis profil V8 per jalankan sehingga pengukuran waktu dan pengambilan profil menggunakan harness yang sama.
Konvensi output tersimpan:
- `pnpm test:startup:bench:smoke` menulis artefak smoke tertarget di `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` menulis artefak suite lengkap di `.artifacts/cli-startup-bench-all.json` menggunakan `runs=5` dan `warmup=1`
- `pnpm test:startup:bench:update` menyegarkan fixture baseline yang di-check-in di `test/fixtures/cli-startup-bench.json` menggunakan `runs=5` dan `warmup=1`
- `pnpm test:startup:bench:save` menulis artefak suite penuh di `.artifacts/cli-startup-bench-all.json` menggunakan `runs=5` dan `warmup=1`
- `pnpm test:startup:bench:update` menyegarkan fixture baseline yang disertakan di `test/fixtures/cli-startup-bench.json` menggunakan `runs=5` dan `warmup=1`
Fixture yang di-check-in:
Fixture yang disertakan:
- `test/fixtures/cli-startup-bench.json`
- Segarkan dengan `pnpm test:startup:bench:update`
@ -125,19 +126,19 @@ Fixture yang di-check-in:
## E2E onboarding (Docker)
Docker bersifat opsional; ini hanya diperlukan untuk pengujian smoke onboarding berbasis kontainer.
Docker bersifat opsional; ini hanya diperlukan untuk uji smoke onboarding dalam kontainer.
Alur cold-start lengkap dalam kontainer Linux bersih:
Alur cold-start penuh dalam kontainer Linux bersih:
```bash
scripts/e2e/onboard-docker.sh
```
Skrip ini menjalankan wizard interaktif melalui pseudo-tty, memverifikasi file config/workspace/session, lalu memulai Gateway dan menjalankan `openclaw health`.
Skrip ini menjalankan wizard interaktif melalui pseudo-tty, memverifikasi file konfigurasi/workspace/sesi, lalu memulai Gateway dan menjalankan `openclaw health`.
## Smoke impor QR (Docker)
Memastikan helper runtime QR yang dikelola dimuat di runtime Docker Node yang didukung (default Node 24, kompatibel Node 22):
Memastikan helper runtime QR yang dipelihara dimuat pada runtime Docker Node yang didukung (Node 24 bawaan, kompatibel Node 22):
```bash
pnpm test:docker:qr
@ -146,4 +147,4 @@ pnpm test:docker:qr
## Terkait
- [Pengujian](/id/help/testing)
- [Pengujian langsung](/id/help/testing-live)
- [Pengujian live](/id/help/testing-live)