diff --git a/docs/id/cli/doctor.md b/docs/id/cli/doctor.md index c1cc65e82..9de4813d6 100644 --- a/docs/id/cli/doctor.md +++ b/docs/id/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - Anda mengalami masalah konektivitas/autentikasi dan menginginkan perbaikan terpandu - - Anda telah memperbarui dan ingin pemeriksaan kewajaran + - Anda telah melakukan pembaruan dan ingin pemeriksaan kewajaran summary: Referensi CLI untuk `openclaw doctor` (pemeriksaan kesehatan + perbaikan terpandu) title: Dokter x-i18n: - generated_at: "2026-04-30T09:39:29Z" + generated_at: "2026-04-30T20:05:34Z" model: gpt-5.5 provider: openai - source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c + source_hash: 265d82a10da086cf89687886e491be018a720b70021e0b26bd8f39b25a907e14 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` -Pemeriksaan kesehatan + perbaikan cepat untuk Gateway dan kanal. +Pemeriksaan kesehatan + perbaikan cepat untuk Gateway dan channel. Terkait: @@ -34,39 +34,40 @@ openclaw doctor --generate-gateway-token ## Opsi -- `--no-workspace-suggestions`: nonaktifkan saran memori/pencarian workspace -- `--yes`: terima nilai default tanpa meminta konfirmasi +- `--no-workspace-suggestions`: nonaktifkan saran pencarian/memori workspace +- `--yes`: terima default tanpa meminta konfirmasi - `--repair`: terapkan perbaikan yang direkomendasikan tanpa meminta konfirmasi - `--fix`: alias untuk `--repair` -- `--force`: terapkan perbaikan agresif, termasuk menimpa konfigurasi layanan kustom bila diperlukan +- `--force`: terapkan perbaikan agresif, termasuk menimpa konfigurasi layanan khusus bila diperlukan - `--non-interactive`: jalankan tanpa prompt; hanya migrasi aman - `--generate-gateway-token`: buat dan konfigurasikan token Gateway - `--deep`: pindai layanan sistem untuk instalasi Gateway tambahan Catatan: -- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan ketika stdin adalah TTY dan `--non-interactive` **tidak** disetel. Eksekusi tanpa terminal (cron, Telegram, tanpa terminal) akan melewati prompt. -- Performa: eksekusi `doctor` noninteraktif melewati pemuatan Plugin secara eager agar pemeriksaan kesehatan tanpa terminal tetap cepat. Sesi interaktif tetap memuat Plugin secara penuh ketika suatu pemeriksaan membutuhkan kontribusinya. -- `--fix` (alias untuk `--repair`) menulis cadangan ke `~/.openclaw/openclaw.json.bak` dan menghapus kunci konfigurasi yang tidak dikenal, dengan mencantumkan setiap penghapusan. -- Pemeriksaan integritas status kini mendeteksi berkas transkrip yatim di direktori sesi. Mengarsipkannya sebagai `.deleted.` memerlukan konfirmasi interaktif; `--fix`, `--yes`, dan eksekusi tanpa terminal membiarkannya tetap di tempat. -- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk pekerjaan Cron lama dan dapat menulis ulangnya langsung sebelum scheduler harus melakukan normalisasi otomatis saat runtime. -- Doctor memperbaiki dependensi runtime Plugin bawaan yang hilang tanpa menulis ke instalasi global terpaket. Untuk instalasi npm milik root atau unit systemd yang diperkeras, setel `OPENCLAW_PLUGIN_STAGE_DIR` ke direktori yang dapat ditulis seperti `/var/lib/openclaw/plugin-runtime-deps`; ini juga dapat berupa daftar path seperti `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, dengan root awal sebagai lapisan pencarian baca-saja dan root terakhir sebagai target perbaikan. -- Doctor memperbaiki konfigurasi Plugin basi dengan menghapus id Plugin yang hilang dari `plugins.allow`/`plugins.entries`, ditambah konfigurasi kanal menggantung yang cocok, target Heartbeat, dan override model kanal ketika penemuan Plugin sehat. -- Doctor mengarantina konfigurasi Plugin yang tidak valid dengan menonaktifkan entri `plugins.entries.` yang terdampak dan menghapus payload `config` yang tidak valid. Startup Gateway sudah hanya melewati Plugin bermasalah itu sehingga Plugin dan kanal lain dapat tetap berjalan. -- Setel `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor lain memiliki siklus hidup Gateway. Doctor tetap melaporkan kesehatan Gateway/layanan dan menerapkan perbaikan non-layanan, tetapi melewati pemasangan/mulai/mulai ulang/bootstrap layanan dan pembersihan layanan lama. -- Di Linux, doctor mengabaikan unit systemd tambahan mirip Gateway yang tidak aktif dan tidak menulis ulang metadata perintah/entrypoint untuk layanan Gateway systemd yang sedang berjalan selama perbaikan. Hentikan layanan terlebih dahulu atau gunakan `openclaw gateway install --force` ketika Anda sengaja ingin mengganti launcher aktif. -- Doctor memigrasikan otomatis konfigurasi Talk flat lama (`talk.voiceId`, `talk.modelId`, dan sejenisnya) ke `talk.provider` + `talk.providers.`. +- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan ketika stdin adalah TTY dan `--non-interactive` **tidak** disetel. Eksekusi headless (cron, Telegram, tanpa terminal) akan melewati prompt. +- Performa: eksekusi `doctor` non-interaktif melewati pemuatan Plugin secara eager agar pemeriksaan kesehatan headless tetap cepat. Sesi interaktif tetap memuat Plugin sepenuhnya ketika sebuah pemeriksaan membutuhkan kontribusinya. +- `--fix` (alias untuk `--repair`) menulis cadangan ke `~/.openclaw/openclaw.json.bak` dan menghapus kunci konfigurasi yang tidak dikenal, sambil mencantumkan setiap penghapusan. +- Pemeriksaan integritas state sekarang mendeteksi file transkrip yatim di direktori sesi. Mengarsipkannya sebagai `.deleted.` memerlukan konfirmasi interaktif; `--fix`, `--yes`, dan eksekusi headless membiarkannya tetap ada. +- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk tugas cron lama dan dapat menulis ulang di tempat sebelum penjadwal harus menormalisasinya otomatis saat runtime. +- Doctor memperbaiki dependensi runtime Plugin bawaan yang hilang tanpa menulis ke instalasi global terpaket. Untuk instalasi npm milik root atau unit systemd yang diperkeras, setel `OPENCLAW_PLUGIN_STAGE_DIR` ke direktori yang dapat ditulis seperti `/var/lib/openclaw/plugin-runtime-deps`; ini juga dapat berupa daftar path seperti `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`, dengan root lebih awal sebagai lapisan lookup hanya-baca dan root terakhir sebagai target perbaikan. +- Doctor memperbaiki konfigurasi Plugin usang dengan menghapus id Plugin yang hilang dari `plugins.allow`/`plugins.entries`, ditambah konfigurasi channel menggantung yang cocok, target Heartbeat, dan override model channel ketika penemuan Plugin sehat. +- Doctor mengarantina konfigurasi Plugin yang tidak valid dengan menonaktifkan entri `plugins.entries.` yang terdampak dan menghapus payload `config` yang tidak valid. Startup Gateway sudah hanya melewati Plugin buruk tersebut sehingga Plugin dan channel lain dapat tetap berjalan. +- Setel `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor lain memiliki siklus hidup Gateway. Doctor tetap melaporkan kesehatan Gateway/layanan dan menerapkan perbaikan non-layanan, tetapi melewati instalasi/mulai/mulai ulang/bootstrap layanan dan pembersihan layanan lama. +- Di Linux, doctor mengabaikan unit systemd mirip Gateway tambahan yang tidak aktif dan tidak menulis ulang metadata command/entrypoint untuk layanan Gateway systemd yang sedang berjalan selama perbaikan. Hentikan layanan terlebih dahulu atau gunakan `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher aktif. +- Doctor otomatis memigrasikan konfigurasi Talk flat lama (`talk.voiceId`, `talk.modelId`, dan sejenisnya) ke `talk.provider` + `talk.providers.`. - Eksekusi `doctor --fix` berulang tidak lagi melaporkan/menerapkan normalisasi Talk ketika satu-satunya perbedaan adalah urutan kunci objek. - Doctor menyertakan pemeriksaan kesiapan pencarian memori dan dapat merekomendasikan `openclaw configure --section model` ketika kredensial embedding hilang. -- Doctor memperingatkan ketika tidak ada pemilik perintah yang dikonfigurasi. Pemilik perintah adalah akun operator manusia yang diizinkan menjalankan perintah khusus pemilik dan menyetujui tindakan berbahaya. Pemasangan DM hanya memungkinkan seseorang berbicara dengan bot; jika Anda menyetujui pengirim sebelum bootstrap pemilik pertama ada, setel `commands.ownerAllowFrom` secara eksplisit. -- Jika mode sandbox diaktifkan tetapi Docker tidak tersedia, doctor melaporkan peringatan bernilai-sinyal tinggi dengan remediasi (`install Docker` atau `openclaw config set agents.defaults.sandbox.mode off`). -- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia di jalur perintah saat ini, doctor melaporkan peringatan baca-saja dan tidak menulis kredensial fallback plaintext. -- Jika inspeksi SecretRef kanal gagal di jalur perbaikan, doctor melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal. -- Resolusi otomatis username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat diresolusi di jalur perintah saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati resolusi otomatis untuk proses itu. +- Doctor memperingatkan ketika tidak ada pemilik command yang dikonfigurasi. Pemilik command adalah akun operator manusia yang diizinkan menjalankan command khusus pemilik dan menyetujui tindakan berbahaya. Pairing DM hanya memungkinkan seseorang berbicara dengan bot; jika Anda menyetujui pengirim sebelum bootstrap pemilik pertama tersedia, setel `commands.ownerAllowFrom` secara eksplisit. +- Doctor memperingatkan ketika agen mode Codex dikonfigurasi dan aset Codex CLI pribadi ada di home Codex operator. Peluncuran app-server Codex lokal menggunakan home terisolasi per agen, jadi gunakan `openclaw migrate codex --dry-run` untuk menginventarisasi aset yang sebaiknya dipromosikan secara sengaja. +- Jika mode sandbox diaktifkan tetapi Docker tidak tersedia, doctor melaporkan peringatan bersinyal tinggi dengan remediasi (`install Docker` atau `openclaw config set agents.defaults.sandbox.mode off`). +- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia di jalur command saat ini, doctor melaporkan peringatan hanya-baca dan tidak menulis kredensial fallback plaintext. +- Jika inspeksi SecretRef channel gagal di jalur fix, doctor melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal. +- Resolusi otomatis username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat di-resolve di jalur command saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati resolusi otomatis untuk pass tersebut. ## macOS: override env `launchctl` -Jika sebelumnya Anda menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai itu menggantikan berkas konfigurasi Anda dan dapat menyebabkan galat “tidak sah” yang persisten. +Jika sebelumnya Anda menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai tersebut menimpa file konfigurasi Anda dan dapat menyebabkan error “unauthorized” yang persisten. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -79,4 +80,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## Terkait - [Referensi CLI](/id/cli) -- [Gateway doctor](/id/gateway/doctor) +- [Doctor Gateway](/id/gateway/doctor) diff --git a/docs/id/cli/migrate.md b/docs/id/cli/migrate.md index 93111dc4e..99db0ee69 100644 --- a/docs/id/cli/migrate.md +++ b/docs/id/cli/migrate.md @@ -2,23 +2,23 @@ read_when: - Anda ingin bermigrasi dari Hermes atau sistem agen lain ke OpenClaw - Anda sedang menambahkan penyedia migrasi milik Plugin -summary: Referensi CLI untuk `openclaw migrate` (impor status dari sistem agen lain) +summary: Referensi CLI untuk `openclaw migrate` (impor keadaan dari sistem agen lain) title: Migrasi x-i18n: - generated_at: "2026-04-30T09:40:40Z" + generated_at: "2026-04-30T20:05:32Z" model: gpt-5.5 provider: openai - source_hash: d3db14c16b8f9dcbf86a4f12558cf4e8555aa9a255637034fb804148996a225e + source_hash: ffcd9e874bdaa0a5195e712d4fccd7b3d53034cb362c7f7462e9c7df72477b1a source_path: cli/migrate.md workflow: 16 --- # `openclaw migrate` -Impor status dari sistem agen lain melalui penyedia migrasi milik plugin. Penyedia bawaan mencakup [Claude](/id/install/migrating-claude) dan [Hermes](/id/install/migrating-hermes); plugin pihak ketiga dapat mendaftarkan penyedia tambahan. +Impor status dari sistem agen lain melalui penyedia migrasi milik Plugin. Penyedia bawaan mencakup status Codex CLI, [Claude](/id/install/migrating-claude), dan [Hermes](/id/install/migrating-hermes); Plugin pihak ketiga dapat mendaftarkan penyedia tambahan. -Untuk panduan bagi pengguna, lihat [Bermigrasi dari Claude](/id/install/migrating-claude) dan [Bermigrasi dari Hermes](/id/install/migrating-hermes). [Hub migrasi](/id/install/migrating) mencantumkan semua jalur. +Untuk panduan yang ditujukan bagi pengguna, lihat [Bermigrasi dari Claude](/id/install/migrating-claude) dan [Bermigrasi dari Hermes](/id/install/migrating-hermes). [Hub migrasi](/id/install/migrating) mencantumkan semua jalur. ## Perintah @@ -26,8 +26,12 @@ Untuk panduan bagi pengguna, lihat [Bermigrasi dari Claude](/id/install/migratin ```bash openclaw migrate list openclaw migrate claude --dry-run +openclaw migrate codex --dry-run +openclaw migrate codex --skill gog-vault77-google-workspace openclaw migrate hermes --dry-run openclaw migrate hermes +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes openclaw migrate apply claude --yes openclaw migrate apply hermes --yes openclaw migrate apply hermes --include-secrets --yes @@ -40,28 +44,31 @@ openclaw onboard --import-from hermes --import-source ~/.hermes Nama penyedia migrasi terdaftar, misalnya `hermes`. Jalankan `openclaw migrate list` untuk melihat penyedia yang terpasang. - Buat rencana lalu keluar tanpa mengubah status. + Buat rencana dan keluar tanpa mengubah status. - Timpa direktori status sumber. Hermes menggunakan `~/.hermes` secara default. + Timpa direktori status sumber. Default Hermes adalah `~/.hermes`. Impor kredensial yang didukung. Nonaktif secara default. - Izinkan penerapan untuk mengganti target yang ada saat rencana melaporkan konflik. + Izinkan penerapan mengganti target yang sudah ada ketika rencana melaporkan konflik. - Lewati prompt konfirmasi. Wajib dalam mode non-interaktif. + Lewati prompt konfirmasi. Wajib dalam mode noninteraktif. + + + Pilih satu item salinan skill berdasarkan nama skill atau id item. Ulangi flag untuk memigrasikan beberapa skill. Jika dihilangkan, migrasi Codex interaktif menampilkan pemilih kotak centang dan migrasi noninteraktif mempertahankan semua skill yang direncanakan. - Lewati pencadangan sebelum penerapan. Memerlukan `--force` saat status OpenClaw lokal ada. + Lewati cadangan sebelum penerapan. Memerlukan `--force` ketika status OpenClaw lokal ada. - Wajib bersama `--no-backup` saat penerapan seharusnya menolak melewati pencadangan. + Wajib bersama `--no-backup` ketika penerapan seharusnya menolak melewati cadangan. - Cetak rencana atau hasil penerapan sebagai JSON. Dengan `--json` dan tanpa `--yes`, penerapan mencetak rencana dan tidak mengubah status. + Cetak rencana atau hasil penerapan sebagai JSON. Dengan `--json` dan tanpa `--yes`, penerapan mencetak rencana dan tidak memutasi status. ## Model keamanan @@ -69,17 +76,17 @@ openclaw onboard --import-from hermes --import-source ~/.hermes `openclaw migrate` mengutamakan pratinjau. - + Penyedia mengembalikan rencana terperinci sebelum apa pun berubah, termasuk konflik, item yang dilewati, dan item sensitif. Rencana JSON, output penerapan, dan laporan migrasi menyunting kunci bertingkat yang tampak seperti rahasia, seperti kunci API, token, header otorisasi, cookie, dan kata sandi. - `openclaw migrate apply ` mempratinjau rencana dan meminta konfirmasi sebelum mengubah status kecuali `--yes` ditetapkan. Dalam mode non-interaktif, penerapan memerlukan `--yes`. + `openclaw migrate apply ` menampilkan pratinjau rencana dan meminta konfirmasi sebelum mengubah status kecuali `--yes` disetel. Dalam mode noninteraktif, penerapan memerlukan `--yes`. - - Penerapan membuat dan memverifikasi cadangan OpenClaw sebelum menerapkan migrasi. Jika belum ada status OpenClaw lokal, langkah pencadangan dilewati dan migrasi dapat berlanjut. Untuk melewati pencadangan saat status ada, berikan `--no-backup` dan `--force`. + + Penerapan membuat dan memverifikasi cadangan OpenClaw sebelum menerapkan migrasi. Jika belum ada status OpenClaw lokal, langkah cadangan dilewati dan migrasi dapat berlanjut. Untuk melewati cadangan ketika status ada, berikan `--no-backup` dan `--force`. - Penerapan menolak melanjutkan saat rencana memiliki konflik. Tinjau rencana, lalu jalankan ulang dengan `--overwrite` jika penggantian target yang ada memang disengaja. Penyedia mungkin tetap menulis cadangan tingkat item untuk file yang ditimpa di direktori laporan migrasi. + Penerapan menolak melanjutkan ketika rencana memiliki konflik. Tinjau rencana, lalu jalankan ulang dengan `--overwrite` jika mengganti target yang sudah ada memang disengaja. Penyedia masih dapat menulis cadangan tingkat item untuk file yang ditimpa di direktori laporan migrasi. Rahasia tidak pernah diimpor secara default. Gunakan `--include-secrets` untuk mengimpor kredensial yang didukung. @@ -91,44 +98,81 @@ openclaw onboard --import-from hermes --import-source ~/.hermes Penyedia Claude bawaan mendeteksi status Claude Code di `~/.claude` secara default. Gunakan `--from ` untuk mengimpor home Claude Code atau root proyek tertentu. -Untuk panduan bagi pengguna, lihat [Bermigrasi dari Claude](/id/install/migrating-claude). +Untuk panduan yang ditujukan bagi pengguna, lihat [Bermigrasi dari Claude](/id/install/migrating-claude). ### Yang diimpor Claude -- `CLAUDE.md` proyek dan `.claude/CLAUDE.md` ke dalam workspace agen OpenClaw. -- `~/.claude/CLAUDE.md` pengguna ditambahkan ke `USER.md` workspace. -- Definisi server MCP dari `.mcp.json` proyek, Claude Code `~/.claude.json`, dan Claude Desktop `claude_desktop_config.json`. +- `CLAUDE.md` proyek dan `.claude/CLAUDE.md` ke dalam ruang kerja agen OpenClaw. +- `~/.claude/CLAUDE.md` pengguna ditambahkan ke `USER.md` ruang kerja. +- Definisi server MCP dari `.mcp.json` proyek, `~/.claude.json` Claude Code, dan `claude_desktop_config.json` Claude Desktop. - Direktori skill Claude yang menyertakan `SKILL.md`. -- File Markdown perintah Claude dikonversi menjadi skills OpenClaw dengan pemanggilan manual saja. +- File Markdown perintah Claude yang dikonversi menjadi skill OpenClaw dengan pemanggilan manual saja. -### Status arsip dan peninjauan manual +### Status arsip dan tinjauan manual -Hook Claude, izin, default lingkungan, memori lokal, aturan berbasis jalur, subagen, cache, rencana, dan riwayat proyek dipertahankan dalam laporan migrasi atau dilaporkan sebagai item peninjauan manual. OpenClaw tidak mengeksekusi hook, menyalin allowlist luas, atau mengimpor status kredensial OAuth/Desktop secara otomatis. +Hook, izin, default lingkungan, memori lokal, aturan berbasis cakupan path, subagen, cache, rencana, dan riwayat proyek Claude dipertahankan dalam laporan migrasi atau dilaporkan sebagai item tinjauan manual. OpenClaw tidak menjalankan hook, menyalin allowlist luas, atau mengimpor status kredensial OAuth/Desktop secara otomatis. + +## Penyedia Codex + +Penyedia Codex bawaan mendeteksi status Codex CLI di `~/.codex` secara default, atau +di `CODEX_HOME` ketika variabel lingkungan itu disetel. Gunakan `--from ` untuk +menginventarisasi home Codex tertentu. + +Gunakan penyedia ini ketika berpindah ke harness Codex OpenClaw dan Anda ingin +mempromosikan aset pribadi Codex CLI yang berguna secara sengaja. Peluncuran +server aplikasi Codex lokal menggunakan direktori `CODEX_HOME` dan `HOME` per agen, +sehingga peluncuran tersebut tidak membaca status pribadi Codex CLI Anda secara default. + +Menjalankan `openclaw migrate codex` di terminal interaktif menampilkan pratinjau rencana +lengkap, lalu membuka pemilih kotak centang untuk item salinan skill sebelum konfirmasi +penerapan akhir. Semua skill dipilih di awal; hapus centang pada skill apa pun yang tidak ingin +disalin ke agen ini. Untuk proses skrip atau eksekusi persis, berikan `--skill ` satu kali +per skill, misalnya: + +```bash +openclaw migrate codex --dry-run --skill gog-vault77-google-workspace +openclaw migrate apply codex --yes --skill gog-vault77-google-workspace +``` + +### Yang diimpor Codex + +- Direktori skill Codex CLI di bawah `$CODEX_HOME/skills`, tidak termasuk cache + `.system` Codex. +- AgentSkills pribadi di bawah `$HOME/.agents/skills`, disalin ke ruang kerja agen + OpenClaw saat ini ketika Anda menginginkan kepemilikan per agen. + +### Status Codex tinjauan manual + +Plugin native Codex, `config.toml`, dan `hooks/hooks.json` native tidak +diaktifkan secara otomatis. Plugin dapat mengekspos server MCP, aplikasi, hook, atau perilaku +eksekusi lainnya, sehingga penyedia melaporkannya untuk ditinjau alih-alih memuatnya +ke dalam OpenClaw. File config dan hook disalin ke laporan migrasi +untuk tinjauan manual. ## Penyedia Hermes -Penyedia Hermes bawaan mendeteksi status di `~/.hermes` secara default. Gunakan `--from ` saat Hermes berada di tempat lain. +Penyedia Hermes bawaan mendeteksi status di `~/.hermes` secara default. Gunakan `--from ` ketika Hermes berada di tempat lain. ### Yang diimpor Hermes - Konfigurasi model default dari `config.yaml`. - Penyedia model yang dikonfigurasi dan endpoint kustom yang kompatibel dengan OpenAI dari `providers` dan `custom_providers`. - Definisi server MCP dari `mcp_servers` atau `mcp.servers`. -- `SOUL.md` dan `AGENTS.md` ke dalam workspace agen OpenClaw. -- `memories/MEMORY.md` dan `memories/USER.md` ditambahkan ke file memori workspace. -- Default konfigurasi memori untuk memori file OpenClaw, plus item arsip atau peninjauan manual untuk penyedia memori eksternal seperti Honcho. +- `SOUL.md` dan `AGENTS.md` ke dalam ruang kerja agen OpenClaw. +- `memories/MEMORY.md` dan `memories/USER.md` ditambahkan ke file memori ruang kerja. +- Default konfigurasi memori untuk memori file OpenClaw, ditambah item arsip atau tinjauan manual untuk penyedia memori eksternal seperti Honcho. - Skills yang menyertakan file `SKILL.md` di bawah `skills//`. -- Nilai konfigurasi per skill dari `skills.config`. +- Nilai config per skill dari `skills.config`. - Kunci API yang didukung dari `.env`, hanya dengan `--include-secrets`. ### Kunci `.env` yang didukung `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. -### Status hanya arsip +### Status arsip saja -Status Hermes yang tidak dapat ditafsirkan dengan aman oleh OpenClaw disalin ke laporan migrasi untuk peninjauan manual, tetapi tidak dimuat ke dalam konfigurasi atau kredensial OpenClaw langsung. Ini mempertahankan status yang buram atau tidak aman tanpa berpura-pura OpenClaw dapat mengeksekusi atau memercayainya secara otomatis: +Status Hermes yang tidak dapat ditafsirkan OpenClaw dengan aman disalin ke laporan migrasi untuk tinjauan manual, tetapi tidak dimuat ke config atau kredensial OpenClaw langsung. Ini mempertahankan status buram atau tidak aman tanpa berpura-pura bahwa OpenClaw dapat mengeksekusi atau mempercayainya secara otomatis: - `plugins/` - `sessions/` @@ -144,9 +188,9 @@ Status Hermes yang tidak dapat ditafsirkan dengan aman oleh OpenClaw disalin ke openclaw doctor ``` -## Kontrak plugin +## Kontrak Plugin -Sumber migrasi adalah plugin. Plugin mendeklarasikan id penyedianya di `openclaw.plugin.json`: +Sumber migrasi adalah Plugin. Sebuah Plugin mendeklarasikan id penyedianya di `openclaw.plugin.json`: ```json { @@ -156,22 +200,22 @@ Sumber migrasi adalah plugin. Plugin mendeklarasikan id penyedianya di `openclaw } ``` -Saat runtime, plugin memanggil `api.registerMigrationProvider(...)`. Penyedia mengimplementasikan `detect`, `plan`, dan `apply`. Core memiliki orkestrasi CLI, kebijakan pencadangan, prompt, output JSON, dan preflight konflik. Core meneruskan rencana yang telah ditinjau ke `apply(ctx, plan)`, dan penyedia boleh membangun ulang rencana hanya saat argumen itu tidak ada demi kompatibilitas. +Saat runtime, Plugin memanggil `api.registerMigrationProvider(...)`. Penyedia mengimplementasikan `detect`, `plan`, dan `apply`. Core memiliki orkestrasi CLI, kebijakan cadangan, prompt, output JSON, dan preflight konflik. Core meneruskan rencana yang telah ditinjau ke `apply(ctx, plan)`, dan penyedia dapat membangun ulang rencana hanya ketika argumen tersebut tidak ada demi kompatibilitas. -Plugin penyedia dapat menggunakan `openclaw/plugin-sdk/migration` untuk konstruksi item dan jumlah ringkasan, plus `openclaw/plugin-sdk/migration-runtime` untuk penyalinan file yang sadar konflik, penyalinan laporan hanya arsip, wrapper config-runtime yang di-cache, dan laporan migrasi. +Plugin penyedia dapat menggunakan `openclaw/plugin-sdk/migration` untuk konstruksi item dan jumlah ringkasan, ditambah `openclaw/plugin-sdk/migration-runtime` untuk salinan file yang sadar konflik, salinan laporan khusus arsip, wrapper config-runtime yang di-cache, dan laporan migrasi. ## Integrasi onboarding -Onboarding dapat menawarkan migrasi saat penyedia mendeteksi sumber yang dikenal. Baik `openclaw onboard --flow import` maupun `openclaw setup --wizard --import-from hermes` menggunakan penyedia migrasi plugin yang sama dan tetap menampilkan pratinjau sebelum menerapkan. +Onboarding dapat menawarkan migrasi ketika penyedia mendeteksi sumber yang dikenal. Baik `openclaw onboard --flow import` maupun `openclaw setup --wizard --import-from hermes` menggunakan penyedia migrasi Plugin yang sama dan tetap menampilkan pratinjau sebelum menerapkan. -Impor onboarding memerlukan penyiapan OpenClaw yang baru. Reset konfigurasi, kredensial, sesi, dan workspace terlebih dahulu jika Anda sudah memiliki status lokal. Impor cadangan-plus-timpa atau impor gabungan dibatasi fitur untuk penyiapan yang sudah ada. +Impor onboarding memerlukan penyiapan OpenClaw yang baru. Reset config, kredensial, sesi, dan ruang kerja terlebih dahulu jika Anda sudah memiliki status lokal. Cadangan-plus-timpa atau impor gabungan dibatasi fitur untuk penyiapan yang sudah ada. ## Terkait -- [Bermigrasi dari Hermes](/id/install/migrating-hermes): panduan bagi pengguna. -- [Bermigrasi dari Claude](/id/install/migrating-claude): panduan bagi pengguna. +- [Bermigrasi dari Hermes](/id/install/migrating-hermes): panduan yang ditujukan bagi pengguna. +- [Bermigrasi dari Claude](/id/install/migrating-claude): panduan yang ditujukan bagi pengguna. - [Bermigrasi](/id/install/migrating): pindahkan OpenClaw ke mesin baru. - [Doctor](/id/gateway/doctor): pemeriksaan kesehatan setelah menerapkan migrasi. -- [Plugin](/id/tools/plugin): pemasangan dan pendaftaran plugin. +- [Plugin](/id/tools/plugin): pemasangan dan pendaftaran Plugin. diff --git a/docs/id/concepts/agent-workspace.md b/docs/id/concepts/agent-workspace.md index 70c4a1570..d88fd13f8 100644 --- a/docs/id/concepts/agent-workspace.md +++ b/docs/id/concepts/agent-workspace.md @@ -1,34 +1,34 @@ --- read_when: - - Anda perlu menjelaskan workspace agen atau tata letak filenya - - Anda ingin mencadangkan atau memigrasikan workspace agen + - Anda perlu menjelaskan ruang kerja agen atau tata letak berkasnya + - Anda ingin mencadangkan atau memigrasikan ruang kerja agen sidebarTitle: Agent workspace -summary: 'Workspace agen: lokasi, tata letak, dan strategi cadangan' -title: Workspace agen +summary: 'Ruang kerja agen: lokasi, tata letak, dan strategi pencadangan' +title: Ruang kerja agen x-i18n: - generated_at: "2026-04-26T11:26:39Z" - model: gpt-5.4 + generated_at: "2026-04-30T20:05:31Z" + model: gpt-5.5 provider: openai - source_hash: 35d59d1f0dec05db30f9166a43bfa519d7299b08d093bbeb905d8f83e5cd022a + source_hash: b1ccf74cbec3ff20f4c1c1ce52f099a7ca3365b2536b0aad6ff1d3a5fafcca0a source_path: concepts/agent-workspace.md - workflow: 15 + workflow: 16 --- -Workspace adalah rumah agen. Ini adalah satu-satunya direktori kerja yang digunakan untuk tool file dan untuk konteks workspace. Jaga agar tetap privat dan perlakukan sebagai memori. +Ruang kerja adalah rumah agen. Ini adalah satu-satunya direktori kerja yang digunakan untuk alat file dan konteks ruang kerja. Jaga agar tetap privat dan perlakukan sebagai memori. -Ini terpisah dari `~/.openclaw/`, yang menyimpan config, kredensial, dan sesi. +Ini terpisah dari `~/.openclaw/`, yang menyimpan konfigurasi, kredensial, dan sesi. -Workspace adalah **cwd default**, bukan sandbox keras. Tool me-resolve path relatif terhadap workspace, tetapi path absolut tetap dapat menjangkau lokasi lain di host kecuali sandboxing diaktifkan. Jika Anda memerlukan isolasi, gunakan [`agents.defaults.sandbox`](/id/gateway/sandboxing) (dan/atau config sandbox per agen). +Ruang kerja adalah **cwd default**, bukan sandbox ketat. Alat menyelesaikan path relatif terhadap ruang kerja, tetapi path absolut tetap dapat menjangkau tempat lain di host kecuali sandboxing diaktifkan. Jika Anda memerlukan isolasi, gunakan [`agents.defaults.sandbox`](/id/gateway/sandboxing) (dan/atau konfigurasi sandbox per agen). -Saat sandboxing diaktifkan dan `workspaceAccess` bukan `"rw"`, tool beroperasi di dalam workspace sandbox di bawah `~/.openclaw/sandboxes`, bukan workspace host Anda. +Saat sandboxing diaktifkan dan `workspaceAccess` bukan `"rw"`, alat beroperasi di dalam ruang kerja sandbox di bawah `~/.openclaw/sandboxes`, bukan ruang kerja host Anda. ## Lokasi default - Default: `~/.openclaw/workspace` -- Jika `OPENCLAW_PROFILE` diatur dan bukan `"default"`, default menjadi `~/.openclaw/workspace-`. -- Override di `~/.openclaw/openclaw.json`: +- Jika `OPENCLAW_PROFILE` disetel dan bukan `"default"`, default menjadi `~/.openclaw/workspace-`. +- Timpa di `~/.openclaw/openclaw.json`: ```json5 { @@ -40,65 +40,65 @@ Saat sandboxing diaktifkan dan `workspaceAccess` bukan `"rw"`, tool beroperasi d } ``` -`openclaw onboard`, `openclaw configure`, atau `openclaw setup` akan membuat workspace dan mengisi file bootstrap jika belum ada. +`openclaw onboard`, `openclaw configure`, atau `openclaw setup` akan membuat ruang kerja dan mengisi file bootstrap jika belum ada. -Salinan seed sandbox hanya menerima file biasa di dalam workspace; alias symlink/hardlink yang di-resolve ke luar workspace sumber akan diabaikan. +Salinan seed sandbox hanya menerima file reguler di dalam ruang kerja; alias symlink/hardlink yang mengarah ke luar ruang kerja sumber akan diabaikan. -Jika Anda sudah mengelola sendiri file workspace, Anda dapat menonaktifkan pembuatan file bootstrap: +Jika Anda sudah mengelola file ruang kerja sendiri, Anda dapat menonaktifkan pembuatan file bootstrap: ```json5 { agents: { defaults: { skipBootstrap: true } } } ``` -## Folder workspace tambahan +## Folder ruang kerja tambahan -Instalasi lama mungkin telah membuat `~/openclaw`. Menyimpan beberapa direktori workspace sekaligus dapat menyebabkan drift auth atau status yang membingungkan, karena hanya satu workspace yang aktif pada satu waktu. +Instalasi lama mungkin telah membuat `~/openclaw`. Menyimpan beberapa direktori ruang kerja dapat menyebabkan kebingungan auth atau drift status, karena hanya satu ruang kerja yang aktif pada satu waktu. -**Rekomendasi:** pertahankan satu workspace aktif. Jika Anda tidak lagi menggunakan folder tambahan tersebut, arsipkan atau pindahkan ke Trash (misalnya `trash ~/openclaw`). Jika Anda sengaja menyimpan beberapa workspace, pastikan `agents.defaults.workspace` menunjuk ke workspace yang aktif. +**Rekomendasi:** pertahankan satu ruang kerja aktif. Jika Anda tidak lagi menggunakan folder tambahan, arsipkan atau pindahkan ke Trash (misalnya `trash ~/openclaw`). Jika Anda sengaja mempertahankan beberapa ruang kerja, pastikan `agents.defaults.workspace` menunjuk ke yang aktif. -`openclaw doctor` akan memberi peringatan saat mendeteksi direktori workspace tambahan. +`openclaw doctor` memperingatkan saat mendeteksi direktori ruang kerja tambahan. -## Peta file workspace +## Peta file ruang kerja -Ini adalah file standar yang diharapkan OpenClaw di dalam workspace: +Berikut adalah file standar yang diharapkan OpenClaw di dalam ruang kerja: - - Instruksi operasional untuk agen dan cara agen harus menggunakan memori. Dimuat pada awal setiap sesi. Tempat yang baik untuk aturan, prioritas, dan detail "bagaimana harus bersikap". + + Instruksi operasi untuk agen dan cara agen harus menggunakan memori. Dimuat pada awal setiap sesi. Tempat yang baik untuk aturan, prioritas, dan detail "cara berperilaku". - Persona, nada, dan batasan. Dimuat di setiap sesi. Panduan: [panduan kepribadian SOUL.md](/id/concepts/soul). + Persona, nada, dan batasan. Dimuat setiap sesi. Panduan: [panduan kepribadian SOUL.md](/id/concepts/soul). - Siapa pengguna dan bagaimana menyapanya. Dimuat di setiap sesi. + Siapa pengguna dan cara menyapa mereka. Dimuat setiap sesi. Nama, vibe, dan emoji agen. Dibuat/diperbarui selama ritual bootstrap. - - Catatan tentang tool dan konvensi lokal Anda. Tidak mengendalikan ketersediaan tool; ini hanya panduan. + + Catatan tentang alat dan konvensi lokal Anda. Tidak mengontrol ketersediaan alat; ini hanya panduan. - - Checklist kecil opsional untuk run heartbeat. Buat tetap singkat agar tidak boros token. + + Daftar periksa kecil opsional untuk run Heartbeat. Buat singkat untuk menghindari pemborosan token. - - Checklist startup opsional yang dijalankan otomatis saat gateway restart (ketika [hook internal](/id/automation/hooks) diaktifkan). Buat tetap singkat; gunakan tool pesan untuk pengiriman keluar. + + Daftar periksa startup opsional yang dijalankan otomatis saat Gateway dimulai ulang (saat [hook internal](/id/automation/hooks) diaktifkan). Buat singkat; gunakan alat pesan untuk pengiriman keluar. - Ritual sekali jalan saat pertama kali. Hanya dibuat untuk workspace yang benar-benar baru. Hapus setelah ritual selesai. + Ritual pertama kali satu kali. Hanya dibuat untuk ruang kerja yang benar-benar baru. Hapus setelah ritual selesai. - Log memori harian (satu file per hari). Direkomendasikan untuk membaca hari ini + kemarin saat sesi dimulai. + Log memori harian (satu file per hari). Disarankan membaca hari ini + kemarin saat sesi dimulai. - - Memori jangka panjang yang dikurasi. Hanya dimuat di sesi utama yang privat (bukan konteks bersama/grup). Lihat [Memori](/id/concepts/memory) untuk alur kerja dan flush memori otomatis. + + Memori jangka panjang terkurasi. Hanya muat di sesi utama yang privat (bukan konteks bersama/grup). Lihat [Memori](/id/concepts/memory) untuk workflow dan flush memori otomatis. - - Skills khusus workspace. Lokasi Skills dengan prioritas tertinggi untuk workspace tersebut. Mengoverride skills agen proyek, skills agen pribadi, Skills terkelola, Skills bawaan, dan `skills.load.extraDirs` saat nama bertabrakan. + + Skills khusus ruang kerja. Lokasi skill dengan prioritas tertinggi untuk ruang kerja tersebut. Menimpa skill agen proyek, skill agen pribadi, skill terkelola, skill bawaan, dan `skills.load.extraDirs` saat nama bertabrakan. File UI Canvas untuk tampilan node (misalnya `canvas/index.html`). @@ -106,43 +106,44 @@ Ini adalah file standar yang diharapkan OpenClaw di dalam workspace: -Jika ada file bootstrap yang hilang, OpenClaw menyuntikkan penanda "file hilang" ke dalam sesi dan melanjutkan. File bootstrap yang besar akan dipotong saat disuntikkan; sesuaikan batas dengan `agents.defaults.bootstrapMaxChars` (default: 12000) dan `agents.defaults.bootstrapTotalMaxChars` (default: 60000). `openclaw setup` dapat membuat ulang default yang hilang tanpa menimpa file yang sudah ada. +Jika ada file bootstrap yang hilang, OpenClaw menyuntikkan penanda "file hilang" ke dalam sesi dan melanjutkan. File bootstrap besar dipotong saat disuntikkan; sesuaikan batas dengan `agents.defaults.bootstrapMaxChars` (default: 12000) dan `agents.defaults.bootstrapTotalMaxChars` (default: 60000). `openclaw setup` dapat membuat ulang default yang hilang tanpa menimpa file yang sudah ada. -## Apa yang TIDAK ada di workspace +## Yang TIDAK ada di ruang kerja -Semua ini berada di bawah `~/.openclaw/` dan TIDAK boleh di-commit ke repo workspace: +Ini berada di bawah `~/.openclaw/` dan TIDAK boleh di-commit ke repo ruang kerja: -- `~/.openclaw/openclaw.json` (config) -- `~/.openclaw/agents//agent/auth-profiles.json` (profil auth model: OAuth + API key) -- `~/.openclaw/credentials/` (status channel/provider ditambah data impor OAuth lama) +- `~/.openclaw/openclaw.json` (konfigurasi) +- `~/.openclaw/agents//agent/auth-profiles.json` (profil auth model: OAuth + kunci API) +- `~/.openclaw/agents//agent/codex-home/` (akun runtime Codex per agen, konfigurasi, skills, plugins, dan status thread native) +- `~/.openclaw/credentials/` (status channel/provider plus data impor OAuth lama) - `~/.openclaw/agents//sessions/` (transkrip sesi + metadata) -- `~/.openclaw/skills/` (Skills terkelola) +- `~/.openclaw/skills/` (skills terkelola) -Jika Anda perlu memigrasikan sesi atau config, salin secara terpisah dan jangan masukkan ke version control. +Jika Anda perlu memigrasikan sesi atau konfigurasi, salin secara terpisah dan jauhkan dari kontrol versi. -## Cadangan Git (direkomendasikan, privat) +## Cadangan Git (disarankan, privat) -Perlakukan workspace sebagai memori privat. Simpan di repo git **privat** agar dapat dicadangkan dan dipulihkan. +Perlakukan ruang kerja sebagai memori privat. Letakkan di repo git **privat** agar dicadangkan dan dapat dipulihkan. -Jalankan langkah-langkah ini di mesin tempat Gateway berjalan (di situlah workspace berada). +Jalankan langkah-langkah ini di mesin tempat Gateway berjalan (di situlah ruang kerja berada). - Jika git terpasang, workspace yang benar-benar baru akan diinisialisasi secara otomatis. Jika workspace ini belum menjadi repo, jalankan: + Jika git terinstal, ruang kerja yang benar-benar baru diinisialisasi otomatis. Jika ruang kerja ini belum menjadi repo, jalankan: ```bash cd ~/.openclaw/workspace git init git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ - git commit -m "Tambahkan workspace agen" + git commit -m "Add agent workspace" ``` - - 1. Buat repository **privat** baru di GitHub. + + 1. Buat repositori **privat** baru di GitHub. 2. Jangan inisialisasi dengan README (menghindari konflik merge). 3. Salin URL remote HTTPS. 4. Tambahkan remote dan push: @@ -159,8 +160,8 @@ Jalankan langkah-langkah ini di mesin tempat Gateway berjalan (di situlah worksp gh repo create openclaw-workspace --private --source . --remote origin --push ``` - - 1. Buat repository **privat** baru di GitLab. + + 1. Buat repositori **privat** baru di GitLab. 2. Jangan inisialisasi dengan README (menghindari konflik merge). 3. Salin URL remote HTTPS. 4. Tambahkan remote dan push: @@ -178,25 +179,25 @@ Jalankan langkah-langkah ini di mesin tempat Gateway berjalan (di situlah worksp ```bash git status git add . - git commit -m "Perbarui memori" + git commit -m "Update memory" git push ``` -## Jangan commit secret +## Jangan commit rahasia -Bahkan di repo privat, hindari menyimpan secret di workspace: +Bahkan di repo privat, hindari menyimpan rahasia di ruang kerja: -- API key, token OAuth, kata sandi, atau kredensial privat. +- Kunci API, token OAuth, kata sandi, atau kredensial privat. - Apa pun di bawah `~/.openclaw/`. - Dump mentah chat atau lampiran sensitif. -Jika Anda harus menyimpan referensi sensitif, gunakan placeholder dan simpan secret sebenarnya di tempat lain (password manager, environment variable, atau `~/.openclaw/`). +Jika Anda harus menyimpan referensi sensitif, gunakan placeholder dan simpan rahasia asli di tempat lain (pengelola kata sandi, variabel lingkungan, atau `~/.openclaw/`). -Contoh awal `.gitignore` yang disarankan: +Starter `.gitignore` yang disarankan: ```gitignore .DS_Store @@ -206,16 +207,16 @@ Contoh awal `.gitignore` yang disarankan: **/secrets* ``` -## Memindahkan workspace ke mesin baru +## Memindahkan ruang kerja ke mesin baru Clone repo ke path yang diinginkan (default `~/.openclaw/workspace`). - - Atur `agents.defaults.workspace` ke path tersebut di `~/.openclaw/openclaw.json`. + + Setel `agents.defaults.workspace` ke path tersebut di `~/.openclaw/openclaw.json`. - + Jalankan `openclaw setup --workspace ` untuk mengisi file yang hilang. @@ -225,12 +226,12 @@ Contoh awal `.gitignore` yang disarankan: ## Catatan lanjutan -- Routing multi-agen dapat menggunakan workspace yang berbeda per agen. Lihat [Routing channel](/id/channels/channel-routing) untuk konfigurasi routing. -- Jika `agents.defaults.sandbox` diaktifkan, sesi non-utama dapat menggunakan workspace sandbox per-sesi di bawah `agents.defaults.sandbox.workspaceRoot`. +- Routing multi-agen dapat menggunakan ruang kerja berbeda per agen. Lihat [Routing channel](/id/channels/channel-routing) untuk konfigurasi routing. +- Jika `agents.defaults.sandbox` diaktifkan, sesi non-utama dapat menggunakan ruang kerja sandbox per sesi di bawah `agents.defaults.sandbox.workspaceRoot`. ## Terkait -- [Heartbeat](/id/gateway/heartbeat) — file workspace HEARTBEAT.md -- [Sandboxing](/id/gateway/sandboxing) — akses workspace di lingkungan sandbox +- [Heartbeat](/id/gateway/heartbeat) — file ruang kerja HEARTBEAT.md +- [Sandboxing](/id/gateway/sandboxing) — akses ruang kerja di lingkungan sandbox - [Sesi](/id/concepts/session) — path penyimpanan sesi -- [Standing orders](/id/automation/standing-orders) — instruksi persisten dalam file workspace +- [Standing orders](/id/automation/standing-orders) — instruksi persisten dalam file ruang kerja diff --git a/docs/id/gateway/security/index.md b/docs/id/gateway/security/index.md index 23246af72..0d6ce469e 100644 --- a/docs/id/gateway/security/index.md +++ b/docs/id/gateway/security/index.md @@ -4,21 +4,21 @@ read_when: summary: Pertimbangan keamanan dan model ancaman untuk menjalankan Gateway AI dengan akses shell title: Keamanan x-i18n: - generated_at: "2026-04-30T09:51:47Z" + generated_at: "2026-04-30T20:05:26Z" model: gpt-5.5 provider: openai - source_hash: 7a1733675f30b5eb8a45eae671aaa8cf41323e16d2543a02ed7bda558c4ebad1 + source_hash: 20cc63aa79aff1ec42a9c1a10037b11ad5dcc1a3a23d9e76842d4ffd9a920ad7 source_path: gateway/security/index.md workflow: 16 --- **Model kepercayaan asisten pribadi.** Panduan ini mengasumsikan satu batas - operator tepercaya per gateway (model asisten pribadi, pengguna tunggal). - OpenClaw **bukan** batas keamanan multi-tenant yang bermusuhan untuk banyak - pengguna adversarial yang berbagi satu agen atau gateway. Jika Anda memerlukan operasi - kepercayaan campuran atau pengguna adversarial, pisahkan batas kepercayaan (gateway + - kredensial terpisah, idealnya pengguna OS atau host terpisah). + operator tepercaya per gateway (model pengguna tunggal, asisten pribadi). + OpenClaw **bukan** batas keamanan multi-tenant yang bermusuhan untuk beberapa + pengguna adversarial yang berbagi satu agen atau gateway. Jika Anda memerlukan + operasi campuran kepercayaan atau pengguna adversarial, pisahkan batas kepercayaan + (gateway + kredensial terpisah, idealnya pengguna OS atau host terpisah). ## Cakupan dulu: model keamanan asisten pribadi @@ -26,11 +26,11 @@ x-i18n: Panduan keamanan OpenClaw mengasumsikan deployment **asisten pribadi**: satu batas operator tepercaya, dengan kemungkinan banyak agen. - Postur keamanan yang didukung: satu pengguna/batas kepercayaan per gateway (sebaiknya satu pengguna OS/host/VPS per batas). -- Bukan batas keamanan yang didukung: satu gateway/agen bersama yang digunakan oleh pengguna yang saling tidak percaya atau adversarial. +- Bukan batas keamanan yang didukung: satu gateway/agen bersama yang digunakan oleh pengguna yang saling tidak tepercaya atau adversarial. - Jika isolasi pengguna adversarial diperlukan, pisahkan berdasarkan batas kepercayaan (gateway + kredensial terpisah, dan idealnya pengguna/host OS terpisah). -- Jika beberapa pengguna yang tidak tepercaya dapat mengirim pesan ke satu agen dengan alat aktif, perlakukan mereka sebagai berbagi otoritas alat terdelegasi yang sama untuk agen tersebut. +- Jika beberapa pengguna yang tidak tepercaya dapat mengirim pesan ke satu agen dengan tool aktif, perlakukan mereka sebagai berbagi otoritas tool terdelegasi yang sama untuk agen tersebut. -Halaman ini menjelaskan hardening **di dalam model tersebut**. Halaman ini tidak mengklaim isolasi multi-tenant bermusuhan pada satu gateway bersama. +Halaman ini menjelaskan pengerasan **dalam model tersebut**. Halaman ini tidak mengklaim isolasi multi-tenant yang bermusuhan pada satu gateway bersama. ## Pemeriksaan cepat: `openclaw security audit` @@ -45,50 +45,50 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` sengaja tetap sempit: ini mengubah kebijakan grup terbuka umum -menjadi allowlist, memulihkan `logging.redactSensitive: "tools"`, memperketat -izin state/konfigurasi/file include, dan menggunakan reset ACL Windows alih-alih +`security audit --fix` sengaja tetap sempit: ini mengubah kebijakan grup umum +yang terbuka menjadi allowlist, memulihkan `logging.redactSensitive: "tools"`, memperketat +izin state/config/include-file, dan menggunakan reset ACL Windows alih-alih POSIX `chmod` saat berjalan di Windows. -Ini menandai footgun umum (paparan autentikasi Gateway, paparan kontrol browser, allowlist yang ditinggikan, izin sistem berkas, persetujuan exec yang permisif, dan paparan alat channel terbuka). +Ini menandai kesalahan umum (paparan auth Gateway, paparan kontrol browser, allowlist yang ditinggikan, izin sistem berkas, approval exec yang permisif, dan paparan tool kanal terbuka). -OpenClaw adalah produk sekaligus eksperimen: Anda menghubungkan perilaku model frontier ke permukaan perpesanan nyata dan alat nyata. **Tidak ada setup yang “sepenuhnya aman”.** Tujuannya adalah bertindak secara sengaja tentang: +OpenClaw adalah produk sekaligus eksperimen: Anda menghubungkan perilaku model frontier ke permukaan pesan nyata dan tool nyata. **Tidak ada setup yang “sepenuhnya aman”.** Tujuannya adalah bersikap sengaja tentang: - siapa yang dapat berbicara dengan bot Anda - di mana bot diizinkan bertindak - apa yang dapat disentuh bot -Mulailah dengan akses terkecil yang masih berfungsi, lalu perluas saat Anda makin yakin. +Mulailah dengan akses terkecil yang masih berfungsi, lalu perluas saat Anda semakin yakin. -### Kepercayaan deployment dan host +### Deployment dan kepercayaan host OpenClaw mengasumsikan batas host dan konfigurasi tepercaya: -- Jika seseorang dapat memodifikasi state/konfigurasi host Gateway (`~/.openclaw`, termasuk `openclaw.json`), perlakukan mereka sebagai operator tepercaya. -- Menjalankan satu Gateway untuk beberapa operator yang saling tidak percaya/adversarial **bukan setup yang direkomendasikan**. -- Untuk tim dengan kepercayaan campuran, pisahkan batas kepercayaan dengan gateway terpisah (atau minimal pengguna/host OS terpisah). +- Jika seseorang dapat mengubah state/config host Gateway (`~/.openclaw`, termasuk `openclaw.json`), perlakukan mereka sebagai operator tepercaya. +- Menjalankan satu Gateway untuk beberapa operator yang saling tidak tepercaya/adversarial **bukan setup yang direkomendasikan**. +- Untuk tim campuran kepercayaan, pisahkan batas kepercayaan dengan gateway terpisah (atau minimal pengguna/host OS terpisah). - Default yang direkomendasikan: satu pengguna per mesin/host (atau VPS), satu gateway untuk pengguna tersebut, dan satu atau beberapa agen di gateway tersebut. -- Di dalam satu instance Gateway, akses operator yang diautentikasi adalah peran control-plane tepercaya, bukan peran tenant per pengguna. -- Pengidentifikasi sesi (`sessionKey`, ID sesi, label) adalah selector routing, bukan token otorisasi. -- Jika beberapa orang dapat mengirim pesan ke satu agen dengan alat aktif, masing-masing dapat mengarahkan set izin yang sama. Isolasi sesi/memori per pengguna membantu privasi, tetapi tidak mengubah agen bersama menjadi otorisasi host per pengguna. +- Di dalam satu instance Gateway, akses operator terautentikasi adalah peran control-plane tepercaya, bukan peran tenant per pengguna. +- Identifier sesi (`sessionKey`, ID sesi, label) adalah selector routing, bukan token otorisasi. +- Jika beberapa orang dapat mengirim pesan ke satu agen dengan tool aktif, masing-masing dari mereka dapat mengarahkan set izin yang sama. Isolasi sesi/memori per pengguna membantu privasi, tetapi tidak mengubah agen bersama menjadi otorisasi host per pengguna. ### Workspace Slack bersama: risiko nyata -Jika "semua orang di Slack dapat mengirim pesan ke bot," risiko intinya adalah otoritas alat terdelegasi: +Jika "semua orang di Slack dapat mengirim pesan ke bot," risiko intinya adalah otoritas tool terdelegasi: -- pengirim mana pun yang diizinkan dapat memicu panggilan alat (`exec`, browser, alat jaringan/file) dalam kebijakan agen; +- pengirim mana pun yang diizinkan dapat memicu panggilan tool (`exec`, browser, tool jaringan/file) dalam kebijakan agen; - injeksi prompt/konten dari satu pengirim dapat menyebabkan tindakan yang memengaruhi state, perangkat, atau output bersama; -- jika satu agen bersama memiliki kredensial/file sensitif, pengirim mana pun yang diizinkan berpotensi mendorong eksfiltrasi melalui penggunaan alat. +- jika satu agen bersama memiliki kredensial/file sensitif, pengirim mana pun yang diizinkan berpotensi mendorong eksfiltrasi melalui penggunaan tool. -Gunakan agen/gateway terpisah dengan alat minimal untuk workflow tim; jaga agen data pribadi tetap privat. +Gunakan agen/gateway terpisah dengan tool minimal untuk workflow tim; jaga agen data pribadi tetap privat. ### Agen bersama perusahaan: pola yang dapat diterima -Ini dapat diterima saat semua orang yang menggunakan agen tersebut berada dalam batas kepercayaan yang sama (misalnya satu tim perusahaan) dan agen tersebut dibatasi ketat untuk bisnis. +Ini dapat diterima ketika semua orang yang menggunakan agen tersebut berada dalam batas kepercayaan yang sama (misalnya satu tim perusahaan) dan agen tersebut dicakup secara ketat untuk bisnis. - jalankan di mesin/VM/container khusus; - gunakan pengguna OS khusus + browser/profil/akun khusus untuk runtime tersebut; -- jangan masuk ke akun Apple/Google pribadi atau profil password-manager/browser pribadi pada runtime tersebut. +- jangan masuk ke runtime tersebut dengan akun Apple/Google pribadi atau profil password-manager/browser pribadi. Jika Anda mencampur identitas pribadi dan perusahaan pada runtime yang sama, Anda meruntuhkan pemisahan dan meningkatkan risiko paparan data pribadi. @@ -96,69 +96,69 @@ Jika Anda mencampur identitas pribadi dan perusahaan pada runtime yang sama, And Perlakukan Gateway dan Node sebagai satu domain kepercayaan operator, dengan peran berbeda: -- **Gateway** adalah control plane dan permukaan kebijakan (`gateway.auth`, kebijakan alat, routing). +- **Gateway** adalah control plane dan permukaan kebijakan (`gateway.auth`, kebijakan tool, routing). - **Node** adalah permukaan eksekusi jarak jauh yang dipasangkan ke Gateway tersebut (perintah, tindakan perangkat, kapabilitas lokal host). -- Pemanggil yang diautentikasi ke Gateway dipercaya pada cakupan Gateway. Setelah pairing, tindakan Node dipercaya sebagai tindakan operator pada Node tersebut. -- Klien backend direct loopback yang diautentikasi dengan token/kata sandi - gateway bersama dapat membuat RPC control-plane internal tanpa menyajikan identitas - perangkat pengguna. Ini bukan bypass pairing jarak jauh atau browser: klien jaringan, - klien Node, klien token perangkat, dan identitas perangkat eksplisit - tetap melalui pairing dan penegakan peningkatan cakupan. -- `sessionKey` adalah pemilihan routing/konteks, bukan autentikasi per pengguna. -- Persetujuan exec (allowlist + tanya) adalah guardrail untuk niat operator, bukan isolasi multi-tenant bermusuhan. -- Default produk OpenClaw untuk setup operator tunggal tepercaya adalah bahwa exec host pada `gateway`/`node` diizinkan tanpa prompt persetujuan (`security="full"`, `ask="off"` kecuali Anda memperketatnya). Default tersebut adalah UX yang disengaja, bukan kerentanan dengan sendirinya. -- Persetujuan exec mengikat konteks permintaan persis dan operand file lokal langsung best-effort; persetujuan tersebut tidak memodelkan secara semantik setiap path loader runtime/interpreter. Gunakan sandboxing dan isolasi host untuk batas yang kuat. +- Pemanggil yang terautentikasi ke Gateway dipercaya pada cakupan Gateway. Setelah pairing, tindakan Node dipercaya sebagai tindakan operator pada Node tersebut. +- Klien backend direct loopback yang terautentikasi dengan token/password gateway + bersama dapat membuat RPC control-plane internal tanpa menyajikan identitas + perangkat pengguna. Ini bukan bypass pairing jarak jauh atau browser: klien + jaringan, klien Node, klien device-token, dan identitas perangkat eksplisit + tetap melewati pairing dan penegakan scope-upgrade. +- `sessionKey` adalah pemilihan routing/konteks, bukan auth per pengguna. +- Approval exec (allowlist + ask) adalah guardrail untuk niat operator, bukan isolasi multi-tenant yang bermusuhan. +- Default produk OpenClaw untuk setup operator tunggal tepercaya adalah bahwa exec host pada `gateway`/`node` diizinkan tanpa prompt approval (`security="full"`, `ask="off"` kecuali Anda memperketatnya). Default tersebut adalah UX yang disengaja, bukan kerentanan dengan sendirinya. +- Approval exec mengikat konteks permintaan persis dan operand file lokal langsung best-effort; approval tersebut tidak memodelkan secara semantik setiap jalur runtime/interpreter loader. Gunakan sandboxing dan isolasi host untuk batas yang kuat. Jika Anda memerlukan isolasi pengguna bermusuhan, pisahkan batas kepercayaan berdasarkan pengguna/host OS dan jalankan gateway terpisah. ## Matriks batas kepercayaan -Gunakan ini sebagai model cepat saat menilai risiko: +Gunakan ini sebagai model cepat saat melakukan triase risiko: -| Batas atau kontrol | Artinya | Salah baca umum | +| Batas atau kontrol | Artinya | Salah tafsir umum | | --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Mengautentikasi pemanggil ke API gateway | "Perlu tanda tangan per pesan pada setiap frame agar aman" | -| `sessionKey` | Kunci routing untuk pemilihan konteks/sesi | "Kunci sesi adalah batas autentikasi pengguna" | -| Guardrail prompt/konten | Mengurangi risiko penyalahgunaan model | "Injeksi prompt saja membuktikan bypass autentikasi" | -| `canvas.eval` / browser evaluate | Kapabilitas operator yang disengaja saat diaktifkan | "Primitive JS eval apa pun otomatis merupakan kerentanan dalam model kepercayaan ini" | -| Shell `!` TUI lokal | Eksekusi lokal yang dipicu operator secara eksplisit | "Perintah kenyamanan shell lokal adalah injeksi jarak jauh" | -| Pairing Node dan perintah Node | Eksekusi jarak jauh level operator pada perangkat yang dipasangkan | "Kontrol perangkat jarak jauh harus diperlakukan sebagai akses pengguna tidak tepercaya secara default" | -| `gateway.nodes.pairing.autoApproveCidrs` | Kebijakan pendaftaran Node jaringan tepercaya opt-in | "Allowlist yang nonaktif secara default adalah kerentanan pairing otomatis" | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Mengautentikasi pemanggil ke API gateway | "Memerlukan tanda tangan per pesan pada setiap frame agar aman" | +| `sessionKey` | Kunci routing untuk pemilihan konteks/sesi | "Session key adalah batas auth pengguna" | +| Guardrail prompt/konten | Mengurangi risiko penyalahgunaan model | "Prompt injection saja membuktikan bypass auth" | +| `canvas.eval` / browser evaluate | Kapabilitas operator yang disengaja saat diaktifkan | "Primitive JS eval apa pun otomatis merupakan vuln dalam model kepercayaan ini" | +| Shell `!` TUI lokal | Eksekusi lokal yang dipicu operator secara eksplisit | "Perintah kemudahan shell lokal adalah injeksi jarak jauh" | +| Pairing Node dan perintah Node | Eksekusi jarak jauh tingkat operator pada perangkat yang dipasangkan | "Kontrol perangkat jarak jauh harus diperlakukan sebagai akses pengguna tidak tepercaya secara default" | +| `gateway.nodes.pairing.autoApproveCidrs` | Kebijakan enrollment Node jaringan tepercaya opt-in | "Allowlist yang nonaktif secara default adalah kerentanan pairing otomatis" | ## Bukan kerentanan secara desain - + Pola ini sering dilaporkan dan biasanya ditutup tanpa tindakan kecuali bypass batas nyata ditunjukkan: -- Rantai yang hanya berupa injeksi prompt tanpa bypass kebijakan, autentikasi, atau sandbox. +- Rantai hanya prompt-injection tanpa bypass kebijakan, auth, atau sandbox. - Klaim yang mengasumsikan operasi multi-tenant bermusuhan pada satu host atau konfigurasi bersama. -- Klaim yang mengklasifikasikan akses normal operator pada jalur baca (misalnya +- Klaim yang mengklasifikasikan akses read-path operator normal (misalnya `sessions.list` / `sessions.preview` / `chat.history`) sebagai IDOR dalam - setup gateway bersama. -- Temuan deployment khusus localhost (misalnya HSTS pada gateway yang hanya loopback). -- Temuan tanda tangan Webhook inbound Discord untuk jalur inbound yang tidak + setup shared-gateway. +- Temuan deployment hanya localhost (misalnya HSTS pada gateway yang hanya loopback). +- Temuan tanda tangan Discord inbound Webhook untuk jalur inbound yang tidak ada di repo ini. -- Laporan yang memperlakukan metadata pairing Node sebagai lapisan persetujuan - per perintah kedua yang tersembunyi untuk `system.run`, padahal batas eksekusi nyata tetap - kebijakan perintah Node global milik gateway ditambah persetujuan exec milik - Node itu sendiri. +- Laporan yang memperlakukan metadata pairing Node sebagai lapisan approval + kedua tersembunyi per perintah untuk `system.run`, padahal batas eksekusi + sebenarnya tetap kebijakan perintah Node global gateway ditambah approval + exec milik Node itu sendiri. - Laporan yang memperlakukan `gateway.nodes.pairing.autoApproveCidrs` yang dikonfigurasi sebagai - kerentanan dengan sendirinya. Pengaturan ini nonaktif secara default, memerlukan - entri CIDR/IP eksplisit, hanya berlaku untuk pairing `role: node` pertama kali dengan - tanpa cakupan yang diminta, dan tidak menyetujui otomatis operator/browser/Control UI, - WebChat, peningkatan peran, peningkatan cakupan, perubahan metadata, perubahan kunci publik, - atau path header trusted-proxy loopback pada host yang sama kecuali autentikasi trusted-proxy loopback diaktifkan secara eksplisit. -- Temuan "otorisasi per pengguna hilang" yang memperlakukan `sessionKey` sebagai - token autentikasi. + kerentanan dengan sendirinya. Pengaturan ini dinonaktifkan secara default, memerlukan + entri CIDR/IP eksplisit, hanya berlaku untuk pairing pertama kali `role: node` dengan + tanpa scope yang diminta, dan tidak meng-auto-approve operator/browser/Control UI, + WebChat, role upgrade, scope upgrade, perubahan metadata, perubahan public-key, + atau jalur header trusted-proxy same-host loopback kecuali auth trusted-proxy loopback diaktifkan secara eksplisit. +- Temuan "otorisasi per pengguna tidak ada" yang memperlakukan `sessionKey` sebagai + token auth. ## Baseline yang diperkeras dalam 60 detik -Gunakan baseline ini terlebih dahulu, lalu aktifkan kembali alat secara selektif per agen tepercaya: +Gunakan baseline ini dulu, lalu aktifkan kembali tool secara selektif per agen tepercaya: ```json5 { @@ -183,16 +183,16 @@ Gunakan baseline ini terlebih dahulu, lalu aktifkan kembali alat secara selektif } ``` -Ini menjaga Gateway hanya lokal, mengisolasi DM, dan menonaktifkan alat control-plane/runtime secara default. +Ini menjaga Gateway hanya lokal, mengisolasi DM, dan menonaktifkan tool control-plane/runtime secara default. ## Aturan cepat inbox bersama -Jika lebih dari satu orang dapat mengirim DM ke bot Anda: +Jika lebih dari satu orang dapat DM bot Anda: -- Setel `session.dmScope: "per-channel-peer"` (atau `"per-account-channel-peer"` untuk channel multi-akun). -- Pertahankan `dmPolicy: "pairing"` atau allowlist yang ketat. -- Jangan pernah menggabungkan DM bersama dengan akses alat yang luas. -- Ini memperkeras inbox kooperatif/bersama, tetapi tidak dirancang sebagai isolasi co-tenant bermusuhan saat pengguna berbagi akses tulis host/konfigurasi. +- Tetapkan `session.dmScope: "per-channel-peer"` (atau `"per-account-channel-peer"` untuk kanal multi-akun). +- Pertahankan `dmPolicy: "pairing"` atau allowlist ketat. +- Jangan pernah menggabungkan DM bersama dengan akses tool yang luas. +- Ini memperkeras inbox kooperatif/bersama, tetapi tidak dirancang sebagai isolasi co-tenant yang bermusuhan saat pengguna berbagi akses tulis host/config. ## Model visibilitas konteks @@ -201,47 +201,48 @@ OpenClaw memisahkan dua konsep: - **Otorisasi pemicu**: siapa yang dapat memicu agen (`dmPolicy`, `groupPolicy`, allowlist, gate mention). - **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke input model (isi balasan, teks yang dikutip, riwayat thread, metadata yang diteruskan). -Allowlist mengatur trigger dan otorisasi perintah. Pengaturan `contextVisibility` mengontrol bagaimana konteks tambahan (balasan yang dikutip, root thread, riwayat yang diambil) difilter: +Allowlist mengatur pemicu dan otorisasi perintah. Pengaturan `contextVisibility` mengontrol bagaimana konteks tambahan (balasan yang dikutip, root thread, riwayat yang diambil) difilter: - `contextVisibility: "all"` (default) mempertahankan konteks tambahan sebagaimana diterima. - `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang diizinkan oleh pemeriksaan allowlist aktif. -- `contextVisibility: "allowlist_quote"` berperilaku seperti `allowlist`, tetapi tetap mempertahankan satu balasan kutipan eksplisit. +- `contextVisibility: "allowlist_quote"` berperilaku seperti `allowlist`, tetapi tetap mempertahankan satu balasan yang dikutip secara eksplisit. -Setel `contextVisibility` per channel atau per room/percakapan. Lihat [Chat Grup](/id/channels/groups#context-visibility-and-allowlists) untuk detail setup. +Tetapkan `contextVisibility` per kanal atau per room/percakapan. Lihat [Obrolan Grup](/id/channels/groups#context-visibility-and-allowlists) untuk detail setup. -Panduan triase advisory: +Panduan triase advisori: -- Klaim yang hanya menunjukkan "model dapat melihat teks yang dikutip atau historis dari pengirim yang tidak masuk daftar izin" adalah temuan pengerasan yang dapat ditangani dengan `contextVisibility`, bukan bypass autentikasi atau batas sandbox dengan sendirinya. -- Agar berdampak pada keamanan, laporan tetap memerlukan bypass batas kepercayaan yang ditunjukkan (autentikasi, kebijakan, sandbox, persetujuan, atau batas terdokumentasi lainnya). +- Klaim yang hanya menunjukkan "model dapat melihat teks yang dikutip atau historis dari pengirim yang tidak ada dalam allowlist" adalah temuan penguatan yang dapat ditangani dengan `contextVisibility`, bukan bypass batas auth atau sandbox dengan sendirinya. +- Agar berdampak pada keamanan, laporan tetap memerlukan bypass batas kepercayaan yang didemonstrasikan (auth, kebijakan, sandbox, persetujuan, atau batas terdokumentasi lainnya). -## Yang diperiksa audit (tingkat tinggi) +## Apa yang diperiksa audit (tingkat tinggi) -- **Akses masuk** (kebijakan DM, kebijakan grup, daftar izin): bisakah orang asing memicu bot? -- **Radius dampak alat** (alat dengan hak tinggi + ruang terbuka): bisakah injeksi prompt berubah menjadi tindakan shell/file/network? -- **Pergeseran persetujuan eksekusi** (`security=full`, `autoAllowSkills`, daftar izin interpreter tanpa `strictInlineEval`): apakah pengaman host-exec masih melakukan yang Anda kira? - - `security="full"` adalah peringatan postur yang luas, bukan bukti bug. Ini adalah default yang dipilih untuk penyiapan asisten pribadi tepercaya; perketat hanya ketika model ancaman Anda memerlukan pengaman persetujuan atau daftar izin. -- **Paparan jaringan** (bind/auth Gateway, Tailscale Serve/Funnel, token auth lemah/pendek). +- **Akses masuk** (kebijakan DM, kebijakan grup, allowlist): dapatkah orang asing memicu bot? +- **Radius dampak alat** (alat dengan hak tinggi + ruang terbuka): dapatkah injeksi prompt berubah menjadi tindakan shell/file/jaringan? +- **Pergeseran persetujuan exec** (`security=full`, `autoAllowSkills`, allowlist interpreter tanpa `strictInlineEval`): apakah guardrail host-exec masih melakukan apa yang Anda kira? + - `security="full"` adalah peringatan postur yang luas, bukan bukti bug. Ini adalah default yang dipilih untuk setup asisten pribadi tepercaya; perketat hanya ketika model ancaman Anda membutuhkan guardrail persetujuan atau allowlist. +- **Paparan jaringan** (bind/auth Gateway, Tailscale Serve/Funnel, token auth yang lemah/pendek). - **Paparan kontrol browser** (node jarak jauh, port relay, endpoint CDP jarak jauh). -- **Kebersihan disk lokal** (izin, symlink, include konfigurasi, path “folder tersinkronisasi”). -- **Plugin** (plugin dimuat tanpa daftar izin eksplisit). -- **Pergeseran kebijakan/salah konfigurasi** (pengaturan docker sandbox dikonfigurasi tetapi mode sandbox mati; pola `gateway.nodes.denyCommands` tidak efektif karena pencocokan hanya nama perintah persis (misalnya `system.run`) dan tidak memeriksa teks shell; entri `gateway.nodes.allowCommands` berbahaya; `tools.profile="minimal"` global ditimpa oleh profil per agen; alat milik plugin dapat dijangkau di bawah kebijakan alat yang permisif). -- **Pergeseran ekspektasi runtime** (misalnya berasumsi exec implisit masih berarti `sandbox` ketika `tools.exec.host` sekarang default ke `auto`, atau secara eksplisit menetapkan `tools.exec.host="sandbox"` sementara mode sandbox mati). -- **Kebersihan model** (beri peringatan ketika model yang dikonfigurasi tampak legacy; bukan pemblokiran keras). +- **Kebersihan disk lokal** (izin, symlink, include konfigurasi, jalur “folder tersinkron”). +- **Plugin** (plugin dimuat tanpa allowlist eksplisit). +- **Pergeseran kebijakan/miskonfigurasi** (pengaturan docker sandbox dikonfigurasi tetapi mode sandbox mati; pola `gateway.nodes.denyCommands` tidak efektif karena pencocokan hanya berdasarkan nama perintah persis (misalnya `system.run`) dan tidak memeriksa teks shell; entri `gateway.nodes.allowCommands` yang berbahaya; `tools.profile="minimal"` global ditimpa oleh profil per agen; alat milik plugin dapat dijangkau di bawah kebijakan alat yang permisif). +- **Pergeseran ekspektasi runtime** (misalnya mengasumsikan exec implisit masih berarti `sandbox` ketika `tools.exec.host` sekarang default ke `auto`, atau secara eksplisit menyetel `tools.exec.host="sandbox"` saat mode sandbox mati). +- **Kebersihan model** (beri peringatan ketika model yang dikonfigurasi tampak legacy; bukan blok keras). -Jika Anda menjalankan `--deep`, OpenClaw juga mencoba probe Gateway live sebaik mungkin. +Jika Anda menjalankan `--deep`, OpenClaw juga mencoba probe Gateway langsung best-effort. ## Peta penyimpanan kredensial Gunakan ini saat mengaudit akses atau memutuskan apa yang perlu dicadangkan: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Token bot Telegram**: config/env atau `channels.telegram.tokenFile` (hanya file biasa; symlink ditolak) +- **Token bot Telegram**: config/env atau `channels.telegram.tokenFile` (hanya file reguler; symlink ditolak) - **Token bot Discord**: config/env atau SecretRef (penyedia env/file/exec) - **Token Slack**: config/env (`channels.slack.*`) -- **Daftar izin pairing**: +- **Allowlist pairing**: - `~/.openclaw/credentials/-allowFrom.json` (akun default) - `~/.openclaw/credentials/--allowFrom.json` (akun non-default) - **Profil auth model**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Status runtime Codex**: `~/.openclaw/agents//agent/codex-home/` - **Payload rahasia berbasis file (opsional)**: `~/.openclaw/secrets.json` - **Impor OAuth legacy**: `~/.openclaw/credentials/oauth.json` @@ -249,55 +250,55 @@ Gunakan ini saat mengaudit akses atau memutuskan apa yang perlu dicadangkan: Ketika audit mencetak temuan, perlakukan ini sebagai urutan prioritas: -1. **Apa pun yang “terbuka” + alat aktif**: kunci DM/grup terlebih dahulu (pairing/daftar izin), lalu perketat kebijakan alat/sandboxing. +1. **Apa pun yang “terbuka” + alat diaktifkan**: kunci DM/grup terlebih dahulu (pairing/allowlist), lalu perketat kebijakan alat/sandboxing. 2. **Paparan jaringan publik** (bind LAN, Funnel, auth hilang): perbaiki segera. 3. **Paparan jarak jauh kontrol browser**: perlakukan seperti akses operator (hanya tailnet, pasangkan node secara sengaja, hindari paparan publik). -4. **Izin**: pastikan state/config/credentials/auth tidak dapat dibaca grup/dunia. -5. **Plugin**: hanya muat yang Anda percayai secara eksplisit. -6. **Pilihan model**: pilih model modern yang diperkeras terhadap instruksi untuk bot apa pun dengan alat. +4. **Izin**: pastikan state/config/kredensial/auth tidak dapat dibaca oleh grup/dunia. +5. **Plugin**: hanya muat yang secara eksplisit Anda percayai. +6. **Pilihan model**: pilih model modern yang diperkuat instruksi untuk bot apa pun dengan alat. ## Glosarium audit keamanan -Setiap temuan audit dikunci oleh `checkId` terstruktur (misalnya +Setiap temuan audit diberi kunci oleh `checkId` terstruktur (misalnya `gateway.bind_no_auth` atau `tools.exec.security_full_configured`). Kelas severity kritis yang umum: -- `fs.*` — izin sistem file pada state, config, kredensial, profil auth. -- `gateway.*` — mode bind, auth, Tailscale, Control UI, penyiapan trusted-proxy. -- `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` — pengerasan per permukaan. +- `fs.*` — izin sistem file pada state, konfigurasi, kredensial, profil auth. +- `gateway.*` — mode bind, auth, Tailscale, Control UI, setup trusted-proxy. +- `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` — penguatan per permukaan. - `plugins.*`, `skills.*` — rantai pasok plugin/skill dan temuan pemindaian. -- `security.exposure.*` — pemeriksaan lintas area tempat kebijakan akses bertemu radius dampak alat. +- `security.exposure.*` — pemeriksaan lintas aspek saat kebijakan akses bertemu radius dampak alat. -Lihat katalog lengkap dengan tingkat severity, kunci perbaikan, dan dukungan perbaikan otomatis di +Lihat katalog lengkap dengan tingkat severity, kunci perbaikan, dan dukungan auto-fix di [Pemeriksaan audit keamanan](/id/gateway/security/audit-checks). ## Control UI melalui HTTP -Control UI memerlukan **konteks aman** (HTTPS atau localhost) untuk menghasilkan identitas +Control UI membutuhkan **konteks aman** (HTTPS atau localhost) untuk menghasilkan identitas perangkat. `gateway.controlUi.allowInsecureAuth` adalah toggle kompatibilitas lokal: -- Di localhost, ini mengizinkan auth Control UI tanpa identitas perangkat ketika halaman - dimuat melalui HTTP yang tidak aman. -- Ini tidak melewati pemeriksaan pairing. +- Pada localhost, ini mengizinkan auth Control UI tanpa identitas perangkat ketika halaman + dimuat melalui HTTP non-aman. +- Ini tidak mem-bypass pemeriksaan pairing. - Ini tidak melonggarkan persyaratan identitas perangkat jarak jauh (non-localhost). -Pilih HTTPS (Tailscale Serve) atau buka UI di `127.0.0.1`. +Utamakan HTTPS (Tailscale Serve) atau buka UI di `127.0.0.1`. -Hanya untuk skenario darurat, `gateway.controlUi.dangerouslyDisableDeviceAuth` -menonaktifkan pemeriksaan identitas perangkat sepenuhnya. Ini adalah penurunan keamanan berat; -biarkan mati kecuali Anda sedang aktif men-debug dan dapat segera mengembalikannya. +Hanya untuk skenario break-glass, `gateway.controlUi.dangerouslyDisableDeviceAuth` +menonaktifkan pemeriksaan identitas perangkat sepenuhnya. Ini adalah penurunan keamanan yang berat; +biarkan mati kecuali Anda sedang aktif melakukan debugging dan dapat mengembalikannya dengan cepat. Terpisah dari flag berbahaya tersebut, `gateway.auth.mode: "trusted-proxy"` yang berhasil -dapat mengizinkan sesi Control UI **operator** tanpa identitas perangkat. Itu adalah +dapat menerima sesi Control UI **operator** tanpa identitas perangkat. Itu adalah perilaku mode auth yang disengaja, bukan pintasan `allowInsecureAuth`, dan tetap -tidak meluas ke sesi Control UI peran node. +tidak meluas ke sesi Control UI berperan node. `openclaw security audit` memperingatkan ketika pengaturan ini diaktifkan. ## Ringkasan flag tidak aman atau berbahaya `openclaw security audit` memunculkan `config.insecure_or_dangerous_flags` ketika -switch debug yang diketahui tidak aman/berbahaya diaktifkan. Biarkan ini tidak disetel di +switch debug yang diketahui tidak aman/berbahaya diaktifkan. Biarkan tidak disetel di produksi. @@ -319,7 +320,7 @@ produksi. - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - Pencocokan nama channel (channel bundel dan plugin; juga tersedia per + Pencocokan nama channel (channel bawaan dan plugin; juga tersedia per `accounts.` jika berlaku): - `channels.discord.dangerouslyAllowNameMatching` @@ -350,13 +351,13 @@ produksi. Jika Anda menjalankan Gateway di belakang reverse proxy (nginx, Caddy, Traefik, dll.), konfigurasikan `gateway.trustedProxies` untuk penanganan IP klien yang diteruskan dengan benar. -Ketika Gateway mendeteksi header proxy dari alamat yang **tidak** ada di `trustedProxies`, Gateway **tidak** akan memperlakukan koneksi sebagai klien lokal. Jika auth gateway dinonaktifkan, koneksi tersebut ditolak. Ini mencegah bypass autentikasi ketika koneksi yang diproksi sebaliknya tampak berasal dari localhost dan menerima kepercayaan otomatis. +Ketika Gateway mendeteksi header proxy dari alamat yang **tidak** ada di `trustedProxies`, ia **tidak** akan memperlakukan koneksi sebagai klien lokal. Jika auth gateway dinonaktifkan, koneksi tersebut ditolak. Ini mencegah bypass autentikasi ketika koneksi yang diproxy jika tidak akan tampak berasal dari localhost dan menerima kepercayaan otomatis. -`gateway.trustedProxies` juga memasok `gateway.auth.mode: "trusted-proxy"`, tetapi mode auth itu lebih ketat: +`gateway.trustedProxies` juga memberi masukan ke `gateway.auth.mode: "trusted-proxy"`, tetapi mode auth tersebut lebih ketat: -- auth trusted-proxy **gagal tertutup pada proxy bersumber loopback secara default** -- reverse proxy loopback host yang sama dapat menggunakan `gateway.trustedProxies` untuk deteksi klien lokal dan penanganan IP yang diteruskan -- reverse proxy loopback host yang sama dapat memenuhi `gateway.auth.mode: "trusted-proxy"` hanya ketika `gateway.auth.trustedProxy.allowLoopback = true`; jika tidak, gunakan auth token/kata sandi +- auth trusted-proxy **gagal tertutup pada proxy sumber-loopback secara default** +- reverse proxy loopback same-host dapat menggunakan `gateway.trustedProxies` untuk deteksi klien lokal dan penanganan IP yang diteruskan +- reverse proxy loopback same-host dapat memenuhi `gateway.auth.mode: "trusted-proxy"` hanya ketika `gateway.auth.trustedProxy.allowLoopback = true`; jika tidak, gunakan auth token/password ```yaml gateway: @@ -372,11 +373,11 @@ gateway: Ketika `trustedProxies` dikonfigurasi, Gateway menggunakan `X-Forwarded-For` untuk menentukan IP klien. `X-Real-IP` diabaikan secara default kecuali `gateway.allowRealIpFallback: true` disetel secara eksplisit. -Header trusted proxy tidak membuat pairing perangkat node otomatis tepercaya. -`gateway.nodes.pairing.autoApproveCidrs` adalah kebijakan operator terpisah yang nonaktif secara default. -Bahkan ketika diaktifkan, jalur header trusted-proxy bersumber loopback -dikecualikan dari persetujuan otomatis node karena pemanggil lokal dapat memalsukan -header tersebut, termasuk ketika auth trusted-proxy loopback diaktifkan secara eksplisit. +Header trusted proxy tidak membuat pairing perangkat node otomatis dipercaya. +`gateway.nodes.pairing.autoApproveCidrs` adalah kebijakan operator terpisah yang defaultnya dinonaktifkan. +Bahkan ketika diaktifkan, jalur header trusted-proxy sumber-loopback +dikecualikan dari auto-approval node karena pemanggil lokal dapat memalsukan header tersebut, +termasuk ketika auth trusted-proxy loopback diaktifkan secara eksplisit. Perilaku reverse proxy yang baik (timpa header forwarding yang masuk): @@ -385,7 +386,7 @@ proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Perilaku reverse proxy yang buruk (tambahkan/pertahankan header forwarding tidak tepercaya): +Perilaku reverse proxy yang buruk (tambahkan/pertahankan header forwarding yang tidak tepercaya): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -393,55 +394,55 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ## Catatan HSTS dan origin -- Gateway OpenClaw mengutamakan lokal/loopback. Jika Anda menghentikan TLS di reverse proxy, setel HSTS pada domain HTTPS yang menghadap proxy di sana. -- Jika gateway itu sendiri menghentikan HTTPS, Anda dapat menyetel `gateway.http.securityHeaders.strictTransportSecurity` untuk memancarkan header HSTS dari respons OpenClaw. +- Gateway OpenClaw mengutamakan lokal/local loopback. Jika Anda mengakhiri TLS di reverse proxy, setel HSTS di domain HTTPS yang menghadap proxy di sana. +- Jika gateway itu sendiri mengakhiri HTTPS, Anda dapat menyetel `gateway.http.securityHeaders.strictTransportSecurity` untuk memancarkan header HSTS dari respons OpenClaw. - Panduan deployment terperinci ada di [Auth Trusted Proxy](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Untuk deployment Control UI non-loopback, `gateway.controlUi.allowedOrigins` diperlukan secara default. -- `gateway.controlUi.allowedOrigins: ["*"]` adalah kebijakan origin browser yang mengizinkan semua secara eksplisit, bukan default yang diperkeras. Hindari di luar pengujian lokal yang dikontrol ketat. -- Kegagalan auth origin browser pada loopback tetap dibatasi lajunya bahkan ketika - pengecualian loopback umum diaktifkan, tetapi kunci lockout dicakup per +- Untuk deployment Control UI non-loopback, `gateway.controlUi.allowedOrigins` diwajibkan secara default. +- `gateway.controlUi.allowedOrigins: ["*"]` adalah kebijakan origin browser allow-all eksplisit, bukan default yang diperkuat. Hindari di luar pengujian lokal yang dikontrol ketat. +- Kegagalan auth origin browser pada loopback tetap dikenai rate limit bahkan ketika + pengecualian loopback umum diaktifkan, tetapi kunci lockout diskop per nilai `Origin` yang dinormalisasi, bukan satu bucket localhost bersama. - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` mengaktifkan mode fallback origin header Host; perlakukan sebagai kebijakan berbahaya yang dipilih operator. -- Perlakukan DNS rebinding dan perilaku header host proxy sebagai perhatian pengerasan deployment; jaga `trustedProxies` tetap ketat dan hindari mengekspos gateway langsung ke internet publik. +- Perlakukan DNS rebinding dan perilaku header proxy-host sebagai perhatian penguatan deployment; jaga `trustedProxies` tetap ketat dan hindari mengekspos gateway langsung ke internet publik. -## Log sesi lokal berada di disk +## Log sesi lokal tersimpan di disk OpenClaw menyimpan transkrip sesi di disk di bawah `~/.openclaw/agents//sessions/*.jsonl`. Ini diperlukan untuk kontinuitas sesi dan (opsional) pengindeksan memori sesi, tetapi juga berarti -**proses/pengguna apa pun dengan akses sistem file dapat membaca log tersebut**. Perlakukan akses disk sebagai batas kepercayaan -dan kunci izin pada `~/.openclaw` (lihat bagian audit di bawah). Jika Anda memerlukan +**proses/pengguna mana pun dengan akses sistem file dapat membaca log tersebut**. Perlakukan akses disk sebagai +batas kepercayaan dan kunci izin pada `~/.openclaw` (lihat bagian audit di bawah). Jika Anda membutuhkan isolasi yang lebih kuat antar agen, jalankan mereka di bawah pengguna OS terpisah atau host terpisah. ## Eksekusi Node (system.run) -Jika node macOS dipasangkan, Gateway dapat memanggil `system.run` pada node tersebut. Ini adalah **eksekusi kode jarak jauh** pada Mac: +Jika node macOS dipasangkan, Gateway dapat memanggil `system.run` pada node tersebut. Ini adalah **eksekusi kode jarak jauh** di Mac: -- Memerlukan pemasangan node (persetujuan + token). -- Pemasangan node Gateway bukan permukaan persetujuan per perintah. Ini menetapkan identitas/kepercayaan node dan penerbitan token. -- Gateway menerapkan kebijakan perintah node global kasar melalui `gateway.nodes.allowCommands` / `denyCommands`. -- Dikendalikan di Mac melalui **Pengaturan → Persetujuan eksekusi** (security + ask + daftar izin). -- Kebijakan `system.run` per node adalah file persetujuan eksekusi milik node sendiri (`exec.approvals.node.*`), yang dapat lebih ketat atau lebih longgar daripada kebijakan ID perintah global gateway. +- Memerlukan pairing node (persetujuan + token). +- Pairing node Gateway bukan permukaan persetujuan per perintah. Pairing ini menetapkan identitas/kepercayaan node dan penerbitan token. +- Gateway menerapkan kebijakan perintah node global yang kasar melalui `gateway.nodes.allowCommands` / `denyCommands`. +- Dikendalikan di Mac melalui **Settings → Exec approvals** (keamanan + tanya + daftar izin). +- Kebijakan `system.run` per node adalah file persetujuan eksekusi milik node itu sendiri (`exec.approvals.node.*`), yang bisa lebih ketat atau lebih longgar daripada kebijakan ID perintah global milik gateway. - Node yang berjalan dengan `security="full"` dan `ask="off"` mengikuti model operator tepercaya bawaan. Perlakukan itu sebagai perilaku yang diharapkan kecuali deployment Anda secara eksplisit memerlukan sikap persetujuan atau daftar izin yang lebih ketat. -- Mode persetujuan mengikat konteks permintaan yang tepat dan, jika memungkinkan, satu operand skrip/file lokal konkret. Jika OpenClaw tidak dapat mengidentifikasi tepat satu file lokal langsung untuk perintah interpreter/runtime, eksekusi berbasis persetujuan ditolak alih-alih menjanjikan cakupan semantik penuh. -- Untuk `host=node`, proses berbasis persetujuan juga menyimpan `systemRunPlan` - yang disiapkan secara kanonis; penerusan yang disetujui kemudian memakai ulang rencana tersimpan itu, dan validasi gateway - menolak edit pemanggil terhadap konteks command/cwd/session setelah +- Mode persetujuan mengikat konteks permintaan persis dan, jika memungkinkan, satu operand skrip/file lokal konkret. Jika OpenClaw tidak dapat mengidentifikasi tepat satu file lokal langsung untuk perintah interpreter/runtime, eksekusi berbasis persetujuan ditolak alih-alih menjanjikan cakupan semantik penuh. +- Untuk `host=node`, eksekusi berbasis persetujuan juga menyimpan `systemRunPlan` + siap pakai yang kanonis; forward yang disetujui kemudian memakai ulang plan tersimpan itu, dan validasi gateway + menolak perubahan pemanggil pada konteks command/cwd/session setelah permintaan persetujuan dibuat. -- Jika Anda tidak menginginkan eksekusi jarak jauh, atur keamanan ke **deny** dan hapus pemasangan node untuk Mac tersebut. +- Jika Anda tidak menginginkan eksekusi jarak jauh, atur keamanan ke **deny** dan hapus pairing node untuk Mac tersebut. -Pembedaan ini penting untuk triase: +Perbedaan ini penting untuk triase: -- Node terpasang yang tersambung ulang dan mengiklankan daftar perintah berbeda bukan, dengan sendirinya, sebuah kerentanan jika kebijakan global Gateway dan persetujuan eksekusi lokal node masih menegakkan batas eksekusi aktual. -- Laporan yang memperlakukan metadata pemasangan node sebagai lapisan persetujuan per perintah tersembunyi kedua biasanya merupakan kebingungan kebijakan/UX, bukan bypass batas keamanan. +- Node berpasangan yang terhubung ulang dan mengiklankan daftar perintah yang berbeda bukanlah, dengan sendirinya, kerentanan jika kebijakan global Gateway dan persetujuan eksekusi lokal node masih menegakkan batas eksekusi aktual. +- Laporan yang memperlakukan metadata pairing node sebagai lapisan persetujuan per perintah kedua yang tersembunyi biasanya merupakan kebingungan kebijakan/UX, bukan bypass batas keamanan. ## Skills dinamis (watcher / node jarak jauh) OpenClaw dapat menyegarkan daftar Skills di tengah sesi: - **Watcher Skills**: perubahan pada `SKILL.md` dapat memperbarui snapshot Skills pada giliran agen berikutnya. -- **Node jarak jauh**: menghubungkan node macOS dapat membuat Skills khusus macOS memenuhi syarat (berdasarkan probing bin). +- **Node jarak jauh**: menghubungkan node macOS dapat membuat Skills khusus macOS menjadi memenuhi syarat (berdasarkan probing bin). -Perlakukan folder skill sebagai **kode tepercaya** dan batasi siapa yang dapat memodifikasinya. +Perlakukan folder Skills sebagai **kode tepercaya** dan batasi siapa yang dapat mengubahnya. ## Model ancaman @@ -455,27 +456,27 @@ Asisten AI Anda dapat: Orang yang mengirimi Anda pesan dapat: - Mencoba menipu AI Anda agar melakukan hal buruk -- Melakukan rekayasa sosial untuk mendapatkan akses ke data Anda -- Menyelidiki detail infrastruktur +- Melakukan rekayasa sosial untuk mengakses data Anda +- Menguji detail infrastruktur ## Konsep inti: kontrol akses sebelum kecerdasan -Sebagian besar kegagalan di sini bukan eksploit canggih — melainkan “seseorang mengirim pesan ke bot dan bot melakukan apa yang diminta.” +Sebagian besar kegagalan di sini bukan exploit canggih — melainkan “seseorang mengirim pesan ke bot dan bot melakukan yang mereka minta.” Sikap OpenClaw: -- **Identitas terlebih dahulu:** tentukan siapa yang dapat berbicara dengan bot (pemasangan DM / daftar izin / “open” eksplisit). +- **Identitas terlebih dahulu:** tentukan siapa yang dapat berbicara dengan bot (pairing DM / daftar izin / “open” eksplisit). - **Cakupan berikutnya:** tentukan di mana bot diizinkan bertindak (daftar izin grup + gating mention, alat, sandboxing, izin perangkat). -- **Model terakhir:** anggap model dapat dimanipulasi; rancang agar manipulasi memiliki radius dampak terbatas. +- **Model terakhir:** asumsikan model dapat dimanipulasi; rancang agar manipulasi memiliki radius dampak terbatas. ## Model otorisasi perintah -Perintah slash dan direktif hanya dihormati untuk **pengirim yang berwenang**. Otorisasi berasal dari -daftar izin/pemasangan channel ditambah `commands.useAccessGroups` (lihat [Konfigurasi](/id/gateway/configuration) +Perintah slash dan direktif hanya dipatuhi untuk **pengirim yang diotorisasi**. Otorisasi diturunkan dari +daftar izin/pairing channel plus `commands.useAccessGroups` (lihat [Konfigurasi](/id/gateway/configuration) dan [Perintah slash](/id/tools/slash-commands)). Jika daftar izin channel kosong atau menyertakan `"*"`, perintah secara efektif terbuka untuk channel tersebut. -`/exec` adalah kemudahan khusus sesi untuk operator yang berwenang. Ini **tidak** menulis konfigurasi atau +`/exec` adalah kemudahan khusus sesi untuk operator yang diotorisasi. Ini **tidak** menulis konfigurasi atau mengubah sesi lain. ## Risiko alat control plane @@ -483,14 +484,14 @@ mengubah sesi lain. Dua alat bawaan dapat membuat perubahan control-plane yang persisten: - `gateway` dapat memeriksa konfigurasi dengan `config.schema.lookup` / `config.get`, dan dapat membuat perubahan persisten dengan `config.apply`, `config.patch`, dan `update.run`. -- `cron` dapat membuat pekerjaan terjadwal yang tetap berjalan setelah chat/tugas asli berakhir. +- `cron` dapat membuat job terjadwal yang terus berjalan setelah chat/tugas asli berakhir. Alat runtime `gateway` khusus pemilik tetap menolak menulis ulang `tools.exec.ask` atau `tools.exec.security`; alias lama `tools.bash.*` -dinormalisasi ke jalur eksekusi terlindungi yang sama sebelum penulisan. +dinormalisasi ke jalur exec terlindungi yang sama sebelum penulisan. Edit `gateway config.apply` dan `gateway config.patch` yang digerakkan agen -gagal-tertutup secara bawaan: hanya sekumpulan sempit jalur prompt, model, dan mention-gating -yang dapat disetel agen. Pohon konfigurasi sensitif baru karenanya terlindungi +gagal tertutup secara bawaan: hanya sekumpulan kecil jalur prompt, model, dan mention-gating +yang dapat disetel agen. Karena itu, pohon konfigurasi sensitif baru terlindungi kecuali sengaja ditambahkan ke daftar izin. Untuk agen/permukaan apa pun yang menangani konten tidak tepercaya, tolak ini secara bawaan: @@ -503,32 +504,32 @@ Untuk agen/permukaan apa pun yang menangani konten tidak tepercaya, tolak ini se } ``` -`commands.restart=false` hanya memblokir tindakan restart. Ini tidak menonaktifkan tindakan konfigurasi/pembaruan `gateway`. +`commands.restart=false` hanya memblokir tindakan restart. Ini tidak menonaktifkan tindakan konfigurasi/update `gateway`. ## Plugin -Plugin berjalan **dalam proses** bersama Gateway. Perlakukan sebagai kode tepercaya: +Plugin berjalan **di dalam proses** bersama Gateway. Perlakukan sebagai kode tepercaya: -- Hanya instal plugin dari sumber yang Anda percayai. -- Lebih pilih daftar izin `plugins.allow` eksplisit. -- Tinjau konfigurasi plugin sebelum mengaktifkan. -- Mulai ulang Gateway setelah perubahan plugin. -- Jika Anda menginstal atau memperbarui plugin (`openclaw plugins install `, `openclaw plugins update `), perlakukan seperti menjalankan kode tidak tepercaya: - - Jalur instal adalah direktori per plugin di bawah root instal plugin aktif. - - OpenClaw menjalankan pemindaian kode berbahaya bawaan sebelum instal/pembaruan. Temuan `critical` memblokir secara bawaan. - - OpenClaw menggunakan `npm pack`, lalu menjalankan `npm install --omit=dev --ignore-scripts` lokal proyek di direktori tersebut. Pengaturan instal npm global yang diwarisi diabaikan agar dependensi tetap berada di bawah jalur instal plugin. - - Lebih pilih versi yang dipin dan eksak (`@scope/pkg@1.2.3`), dan periksa kode yang telah diekstrak di disk sebelum mengaktifkan. - - `--dangerously-force-unsafe-install` hanya untuk situasi darurat terhadap false positive pemindaian bawaan pada alur instal/pembaruan plugin. Ini tidak melewati blok kebijakan hook `before_install` plugin dan tidak melewati kegagalan pemindaian. - - Instal dependensi skill yang didukung Gateway mengikuti pemisahan berbahaya/mencurigakan yang sama: temuan `critical` bawaan memblokir kecuali pemanggil secara eksplisit menetapkan `dangerouslyForceUnsafeInstall`, sementara temuan mencurigakan tetap hanya memperingatkan. `openclaw skills install` tetap merupakan alur download/instal skill ClawHub yang terpisah. +- Hanya instal Plugin dari sumber yang Anda percayai. +- Utamakan daftar izin `plugins.allow` yang eksplisit. +- Tinjau konfigurasi Plugin sebelum mengaktifkan. +- Restart Gateway setelah perubahan Plugin. +- Jika Anda menginstal atau memperbarui Plugin (`openclaw plugins install `, `openclaw plugins update `), perlakukan seperti menjalankan kode tidak tepercaya: + - Jalur instalasi adalah direktori per Plugin di bawah root instalasi Plugin aktif. + - OpenClaw menjalankan pemindaian kode berbahaya bawaan sebelum install/update. Temuan `critical` memblokir secara bawaan. + - OpenClaw menggunakan `npm pack`, lalu menjalankan `npm install --omit=dev --ignore-scripts` lokal proyek di direktori tersebut. Pengaturan instalasi npm global yang diwarisi diabaikan agar dependensi tetap berada di bawah jalur instalasi Plugin. + - Utamakan versi yang dipin dan eksak (`@scope/pkg@1.2.3`), dan periksa kode yang dibongkar di disk sebelum mengaktifkan. + - `--dangerously-force-unsafe-install` hanya untuk keadaan darurat pada false positive pemindaian bawaan dalam alur install/update Plugin. Ini tidak melewati blok kebijakan hook `before_install` Plugin dan tidak melewati kegagalan pemindaian. + - Instalasi dependensi Skills yang didukung Gateway mengikuti pemisahan berbahaya/mencurigakan yang sama: temuan `critical` bawaan memblokir kecuali pemanggil secara eksplisit menetapkan `dangerouslyForceUnsafeInstall`, sementara temuan mencurigakan tetap hanya memperingatkan. `openclaw skills install` tetap merupakan alur unduh/instal Skills ClawHub yang terpisah. Detail: [Plugin](/id/tools/plugin) -## Model akses DM: pemasangan, daftar izin, terbuka, dinonaktifkan +## Model akses DM: pairing, daftar izin, terbuka, dinonaktifkan -Semua channel yang saat ini mendukung DM mendukung kebijakan DM (`dmPolicy` atau `*.dm.policy`) yang memagari DM masuk **sebelum** pesan diproses: +Semua channel yang saat ini mendukung DM mendukung kebijakan DM (`dmPolicy` atau `*.dm.policy`) yang mengatur DM masuk **sebelum** pesan diproses: -- `pairing` (bawaan): pengirim tidak dikenal menerima kode pemasangan singkat dan bot mengabaikan pesan mereka hingga disetujui. Kode kedaluwarsa setelah 1 jam; DM berulang tidak akan mengirim ulang kode hingga permintaan baru dibuat. Permintaan tertunda dibatasi pada **3 per channel** secara bawaan. -- `allowlist`: pengirim tidak dikenal diblokir (tanpa handshake pemasangan). +- `pairing` (bawaan): pengirim tidak dikenal menerima kode pairing singkat dan bot mengabaikan pesan mereka sampai disetujui. Kode kedaluwarsa setelah 1 jam; DM berulang tidak akan mengirim ulang kode sampai permintaan baru dibuat. Permintaan tertunda dibatasi pada **3 per channel** secara bawaan. +- `allowlist`: pengirim tidak dikenal diblokir (tanpa handshake pairing). - `open`: izinkan siapa pun mengirim DM (publik). **Memerlukan** daftar izin channel menyertakan `"*"` (opt-in eksplisit). - `disabled`: abaikan DM masuk sepenuhnya. @@ -539,7 +540,7 @@ openclaw pairing list openclaw pairing approve ``` -Detail + file di disk: [Pemasangan](/id/channels/pairing) +Detail + file di disk: [Pairing](/id/channels/pairing) ## Isolasi sesi DM (mode multi-pengguna) @@ -551,18 +552,18 @@ Secara bawaan, OpenClaw merutekan **semua DM ke sesi utama** agar asisten Anda m } ``` -Ini mencegah kebocoran konteks lintas pengguna sambil tetap menjaga chat grup terisolasi. +Ini mencegah kebocoran konteks lintas pengguna sambil menjaga chat grup tetap terisolasi. -Ini adalah batas konteks perpesanan, bukan batas admin host. Jika pengguna saling bermusuhan dan berbagi host/konfigurasi Gateway yang sama, jalankan gateway terpisah per batas kepercayaan. +Ini adalah batas konteks pesan, bukan batas admin host. Jika pengguna saling bermusuhan dan berbagi host/konfigurasi Gateway yang sama, jalankan gateway terpisah untuk setiap batas kepercayaan. ### Mode DM aman (direkomendasikan) Perlakukan snippet di atas sebagai **mode DM aman**: - Bawaan: `session.dmScope: "main"` (semua DM berbagi satu sesi untuk kontinuitas). -- Bawaan onboarding CLI lokal: menulis `session.dmScope: "per-channel-peer"` saat belum disetel (mempertahankan nilai eksplisit yang sudah ada). -- Mode DM aman: `session.dmScope: "per-channel-peer"` (setiap pasangan channel+pengirim mendapatkan konteks DM terisolasi). -- Isolasi peer lintas channel: `session.dmScope: "per-peer"` (setiap pengirim mendapatkan satu sesi di semua channel dengan tipe yang sama). +- Bawaan onboarding CLI lokal: menulis `session.dmScope: "per-channel-peer"` saat belum diatur (mempertahankan nilai eksplisit yang ada). +- Mode DM aman: `session.dmScope: "per-channel-peer"` (setiap pasangan channel+pengirim mendapat konteks DM terisolasi). +- Isolasi peer lintas channel: `session.dmScope: "per-peer"` (setiap pengirim mendapat satu sesi di semua channel dengan tipe yang sama). Jika Anda menjalankan beberapa akun pada channel yang sama, gunakan `per-account-channel-peer` sebagai gantinya. Jika orang yang sama menghubungi Anda di beberapa channel, gunakan `session.identityLinks` untuk menggabungkan sesi DM tersebut menjadi satu identitas kanonis. Lihat [Manajemen Sesi](/id/concepts/session) dan [Konfigurasi](/id/gateway/configuration). @@ -571,88 +572,88 @@ Jika Anda menjalankan beberapa akun pada channel yang sama, gunakan `per-account OpenClaw memiliki dua lapisan “siapa yang dapat memicu saya?” yang terpisah: - **Daftar izin DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; lama: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): siapa yang diizinkan berbicara dengan bot dalam pesan langsung. - - Saat `dmPolicy="pairing"`, persetujuan ditulis ke penyimpanan daftar izin pemasangan berskala akun di bawah `~/.openclaw/credentials/` (`-allowFrom.json` untuk akun bawaan, `--allowFrom.json` untuk akun non-bawaan), digabungkan dengan daftar izin konfigurasi. + - Saat `dmPolicy="pairing"`, persetujuan ditulis ke penyimpanan daftar izin pairing bercakupan akun di bawah `~/.openclaw/credentials/` (`-allowFrom.json` untuk akun bawaan, `--allowFrom.json` untuk akun non-bawaan), digabungkan dengan daftar izin konfigurasi. - **Daftar izin grup** (khusus channel): grup/channel/guild mana yang akan diterima pesannya oleh bot sama sekali. - Pola umum: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: bawaan per grup seperti `requireMention`; saat disetel, ini juga bertindak sebagai daftar izin grup (sertakan `"*"` untuk mempertahankan perilaku izinkan-semua). - - `groupPolicy="allowlist"` + `groupAllowFrom`: batasi siapa yang dapat memicu bot _di dalam_ sesi grup (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: bawaan per grup seperti `requireMention`; saat diatur, ini juga bertindak sebagai daftar izin grup (sertakan `"*"` untuk mempertahankan perilaku izinkan semua). + - `groupPolicy="allowlist"` + `groupAllowFrom`: membatasi siapa yang dapat memicu bot _di dalam_ sesi grup (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - `channels.discord.guilds` / `channels.slack.channels`: daftar izin per permukaan + bawaan mention. - Pemeriksaan grup berjalan dalam urutan ini: `groupPolicy`/daftar izin grup terlebih dahulu, aktivasi mention/balasan kedua. - Membalas pesan bot (mention implisit) **tidak** melewati daftar izin pengirim seperti `groupAllowFrom`. - - **Catatan keamanan:** perlakukan `dmPolicy="open"` dan `groupPolicy="open"` sebagai pengaturan pilihan terakhir. Keduanya seharusnya sangat jarang digunakan; lebih pilih pemasangan + daftar izin kecuali Anda sepenuhnya memercayai setiap anggota ruangan. + - **Catatan keamanan:** perlakukan `dmPolicy="open"` dan `groupPolicy="open"` sebagai pengaturan pilihan terakhir. Keduanya seharusnya sangat jarang digunakan; utamakan pairing + daftar izin kecuali Anda sepenuhnya memercayai setiap anggota ruangan. Detail: [Konfigurasi](/id/gateway/configuration) dan [Grup](/id/channels/groups) ## Prompt injection (apa itu, mengapa penting) -Prompt injection adalah saat penyerang membuat pesan yang memanipulasi model agar melakukan sesuatu yang tidak aman (“abaikan instruksi Anda”, “dump filesystem Anda”, “ikuti tautan ini dan jalankan perintah”, dsb.). +Prompt injection adalah ketika penyerang merancang pesan yang memanipulasi model agar melakukan sesuatu yang tidak aman (“abaikan instruksi Anda”, “dump filesystem Anda”, “ikuti tautan ini dan jalankan perintah”, dll.). -Bahkan dengan system prompt yang kuat, **prompt injection belum terselesaikan**. Guardrail system prompt hanya panduan lunak; penegakan keras berasal dari kebijakan alat, persetujuan eksekusi, sandboxing, dan daftar izin channel (dan operator dapat menonaktifkannya secara desain). Yang membantu dalam praktik: +Bahkan dengan prompt sistem yang kuat, **prompt injection belum terselesaikan**. Guardrail prompt sistem hanyalah panduan lunak; penegakan keras berasal dari kebijakan alat, persetujuan exec, sandboxing, dan daftar izin channel (dan operator dapat menonaktifkannya sesuai rancangan). Yang membantu dalam praktik: -- Tetap kunci DM masuk (pairing/daftar izin). -- Utamakan pembatasan berdasarkan mention di grup; hindari bot “selalu aktif” di ruang publik. +- Tetap batasi DM masuk (pairing/daftar izinkan). +- Utamakan pembatasan berbasis mention di grup; hindari bot yang “selalu aktif” di ruang publik. - Perlakukan tautan, lampiran, dan instruksi yang ditempel sebagai berbahaya secara default. -- Jalankan eksekusi alat sensitif di sandbox; jauhkan rahasia dari filesystem yang dapat dijangkau agen. -- Catatan: sandboxing bersifat ikut serta. Jika mode sandbox nonaktif, `host=auto` implisit akan diselesaikan ke host gateway. `host=sandbox` eksplisit tetap gagal secara tertutup karena runtime sandbox tidak tersedia. Tetapkan `host=gateway` jika Anda ingin perilaku itu eksplisit dalam config. -- Batasi alat berisiko tinggi (`exec`, `browser`, `web_fetch`, `web_search`) untuk agen tepercaya atau daftar izin eksplisit. -- Jika Anda mengizinkan interpreter (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), aktifkan `tools.exec.strictInlineEval` agar bentuk eval inline tetap memerlukan persetujuan eksplisit. -- Analisis persetujuan shell juga menolak bentuk ekspansi parameter POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) di dalam **heredoc tanpa kutip**, sehingga isi heredoc yang diizinkan tidak dapat menyelundupkan ekspansi shell melewati tinjauan daftar izin sebagai teks biasa. Kutip terminator heredoc (misalnya `<<'EOF'`) untuk memilih semantik isi literal; heredoc tanpa kutip yang akan mengekspansi variabel akan ditolak. +- Jalankan eksekusi alat sensitif di sandbox; jauhkan rahasia dari sistem file yang dapat dijangkau agen. +- Catatan: sandboxing bersifat opt-in. Jika mode sandbox nonaktif, `host=auto` implisit akan diselesaikan ke host Gateway. `host=sandbox` eksplisit tetap gagal tertutup karena tidak ada runtime sandbox yang tersedia. Tetapkan `host=gateway` jika Anda ingin perilaku itu eksplisit dalam konfigurasi. +- Batasi alat berisiko tinggi (`exec`, `browser`, `web_fetch`, `web_search`) hanya untuk agen tepercaya atau daftar izinkan eksplisit. +- Jika Anda memasukkan interpreter ke daftar izinkan (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), aktifkan `tools.exec.strictInlineEval` agar bentuk eval inline tetap memerlukan persetujuan eksplisit. +- Analisis persetujuan shell juga menolak bentuk ekspansi parameter POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) di dalam **heredoc tanpa tanda kutip**, sehingga isi heredoc yang masuk daftar izinkan tidak dapat menyelundupkan ekspansi shell melewati tinjauan daftar izinkan sebagai teks biasa. Beri tanda kutip pada terminator heredoc (misalnya `<<'EOF'`) untuk memilih semantik isi literal; heredoc tanpa tanda kutip yang akan mengekspansi variabel akan ditolak. - **Pilihan model penting:** model lama/lebih kecil/legacy jauh kurang tangguh terhadap injeksi prompt dan penyalahgunaan alat. Untuk agen yang mengaktifkan alat, gunakan model generasi terbaru yang paling kuat dan diperkeras untuk instruksi yang tersedia. Tanda bahaya yang harus diperlakukan sebagai tidak tepercaya: - “Baca file/URL ini dan lakukan persis seperti yang tertulis.” - “Abaikan prompt sistem atau aturan keselamatan Anda.” -- “Ungkapkan instruksi tersembunyi atau keluaran alat Anda.” +- “Ungkap instruksi tersembunyi atau keluaran alat Anda.” - “Tempelkan seluruh isi ~/.openclaw atau log Anda.” -## Sanitisasi token khusus konten eksternal +## Sanitasi token khusus konten eksternal -OpenClaw menghapus literal token khusus template chat LLM self-hosted umum dari konten eksternal dan metadata yang dibungkus sebelum mencapai model. Keluarga penanda yang dicakup meliputi token peran/giliran Qwen/ChatML, Llama, Gemma, Mistral, Phi, dan GPT-OSS. +OpenClaw menghapus literal token khusus templat chat LLM self-hosted umum dari konten eksternal yang dibungkus dan metadata sebelum mencapai model. Keluarga penanda yang dicakup mencakup token peran/giliran Qwen/ChatML, Llama, Gemma, Mistral, Phi, dan GPT-OSS. Alasannya: -- Backend yang kompatibel dengan OpenAI dan berada di depan model self-hosted terkadang mempertahankan token khusus yang muncul dalam teks pengguna, alih-alih menyamarkannya. Penyerang yang dapat menulis ke konten eksternal masuk (halaman yang diambil, isi email, keluaran alat isi file) jika tidak dapat menyuntikkan batas peran `assistant` atau `system` sintetis dan keluar dari pagar pembatas konten terbungkus. -- Sanitisasi terjadi pada lapisan pembungkus konten eksternal, sehingga berlaku seragam di seluruh alat fetch/read dan konten channel masuk, bukan per penyedia. -- Respons model keluar sudah memiliki sanitizer terpisah yang menghapus ``, ``, ``, ``, dan scaffolding runtime internal serupa yang bocor dari balasan yang terlihat pengguna pada batas pengiriman channel akhir. Sanitizer konten eksternal adalah padanan masuknya. +- Backend yang kompatibel dengan OpenAI yang menjadi front bagi model self-hosted terkadang mempertahankan token khusus yang muncul dalam teks pengguna, alih-alih menutupinya. Penyerang yang dapat menulis ke konten eksternal masuk (halaman yang diambil, isi email, keluaran alat isi file) jika tidak begitu dapat menyuntikkan batas peran `assistant` atau `system` sintetis dan lolos dari pengaman konten terbungkus. +- Sanitasi terjadi pada lapisan pembungkus konten eksternal, sehingga diterapkan secara seragam di seluruh alat fetch/read dan konten channel masuk, bukan per penyedia. +- Respons model keluar sudah memiliki sanitizer terpisah yang menghapus kebocoran ``, ``, ``, ``, dan scaffolding runtime internal serupa dari balasan yang terlihat pengguna pada batas pengiriman channel akhir. Sanitizer konten eksternal adalah padanan sisi masuknya. -Ini tidak menggantikan pengerasan lain di halaman ini — `dmPolicy`, daftar izin, persetujuan exec, sandboxing, dan `contextVisibility` tetap melakukan pekerjaan utama. Ini menutup satu bypass lapisan tokenizer spesifik terhadap stack self-hosted yang meneruskan teks pengguna dengan token khusus tetap utuh. +Ini tidak menggantikan penguatan lain di halaman ini — `dmPolicy`, daftar izinkan, persetujuan exec, sandboxing, dan `contextVisibility` tetap melakukan pekerjaan utama. Ini menutup satu bypass spesifik pada lapisan tokenizer terhadap stack self-hosted yang meneruskan teks pengguna dengan token khusus tetap utuh. ## Flag bypass konten eksternal tidak aman -OpenClaw menyertakan flag bypass eksplisit yang menonaktifkan pembungkus keamanan konten eksternal: +OpenClaw menyertakan flag bypass eksplisit yang menonaktifkan pembungkusan keamanan konten eksternal: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` -- Bidang payload Cron `allowUnsafeExternalContent` +- Kolom payload Cron `allowUnsafeExternalContent` Panduan: - Biarkan tidak disetel/false di produksi. -- Aktifkan hanya sementara untuk debugging yang cakupannya sangat ketat. +- Aktifkan hanya sementara untuk debugging dengan cakupan ketat. - Jika diaktifkan, isolasi agen tersebut (sandbox + alat minimal + namespace sesi khusus). Catatan risiko hooks: -- Payload hook adalah konten tidak tepercaya, bahkan ketika pengiriman berasal dari sistem yang Anda kendalikan (konten mail/docs/web dapat membawa injeksi prompt). -- Tingkat model yang lemah meningkatkan risiko ini. Untuk otomasi yang digerakkan hook, utamakan tingkat model modern yang kuat dan jaga kebijakan alat tetap ketat (`tools.profile: "messaging"` atau lebih ketat), plus sandboxing jika memungkinkan. +- Payload hook adalah konten tidak tepercaya, bahkan ketika pengiriman berasal dari sistem yang Anda kendalikan (konten email/dokumen/web dapat membawa injeksi prompt). +- Tingkat model yang lemah meningkatkan risiko ini. Untuk otomatisasi berbasis hook, utamakan tingkat model modern yang kuat dan jaga kebijakan alat tetap ketat (`tools.profile: "messaging"` atau lebih ketat), serta isolasi sandbox jika memungkinkan. ### Injeksi prompt tidak memerlukan DM publik Bahkan jika **hanya Anda** yang dapat mengirim pesan ke bot, injeksi prompt tetap dapat terjadi melalui -**konten tidak tepercaya** apa pun yang dibaca bot (hasil web search/fetch, halaman browser, +**konten tidak tepercaya** apa pun yang dibaca bot (hasil pencarian/pengambilan web, halaman browser, email, dokumen, lampiran, log/kode yang ditempel). Dengan kata lain: pengirim bukan satu-satunya permukaan ancaman; **konten itu sendiri** dapat membawa instruksi adversarial. -Saat alat diaktifkan, risiko tipikalnya adalah eksfiltrasi konteks atau pemicu -pemanggilan alat. Kurangi radius dampak dengan: +Saat alat diaktifkan, risiko umumnya adalah mengekstraksi konteks atau memicu +panggilan alat. Kurangi radius dampaknya dengan: -- Menggunakan **agen pembaca** read-only atau tanpa alat untuk meringkas konten tidak tepercaya, - lalu meneruskan ringkasan ke agen utama Anda. -- Menonaktifkan `web_search` / `web_fetch` / `browser` untuk agen yang mengaktifkan alat kecuali diperlukan. +- Menggunakan **agen pembaca** hanya-baca atau tanpa alat untuk merangkum konten tidak tepercaya, + lalu meneruskan ringkasan tersebut ke agen utama Anda. +- Menonaktifkan `web_search` / `web_fetch` / `browser` untuk agen dengan alat aktif kecuali diperlukan. - Untuk input URL OpenResponses (`input_file` / `input_image`), tetapkan `gateway.http.endpoints.responses.files.urlAllowlist` dan - `gateway.http.endpoints.responses.images.urlAllowlist` yang ketat, dan pertahankan `maxUrlParts` rendah. + `gateway.http.endpoints.responses.images.urlAllowlist` secara ketat, dan pertahankan `maxUrlParts` tetap rendah. Daftar izin kosong diperlakukan sebagai tidak disetel; gunakan `files.allowUrl: false` / `images.allowUrl: false` jika Anda ingin menonaktifkan pengambilan URL sepenuhnya. - Untuk input file OpenResponses, teks `input_file` yang didekode tetap disuntikkan sebagai @@ -660,60 +661,51 @@ pemanggilan alat. Kurangi radius dampak dengan: Gateway mendekodenya secara lokal. Blok yang disuntikkan tetap membawa penanda batas `<<>>` eksplisit plus metadata `Source: External`, meskipun jalur ini menghilangkan banner `SECURITY NOTICE:` yang lebih panjang. -- Pembungkus berbasis penanda yang sama diterapkan saat pemahaman media mengekstrak teks +- Pembungkusan berbasis penanda yang sama diterapkan saat pemahaman media mengekstrak teks dari dokumen terlampir sebelum menambahkan teks tersebut ke prompt media. -- Mengaktifkan sandboxing dan daftar izin alat yang ketat untuk setiap agen yang menyentuh input tidak tepercaya. -- Menjauhkan rahasia dari prompt; teruskan melalui env/config pada host gateway sebagai gantinya. +- Mengaktifkan isolasi sandbox dan daftar izin alat yang ketat untuk setiap agen yang menyentuh input tidak tepercaya. +- Menjauhkan rahasia dari prompt; teruskan melalui env/konfigurasi pada host gateway sebagai gantinya. -### Backend LLM self-hosted +### Backend LLM yang di-host sendiri -Backend self-hosted yang kompatibel dengan OpenAI seperti vLLM, SGLang, TGI, LM Studio, -atau stack tokenizer Hugging Face kustom dapat berbeda dari penyedia hosted dalam cara -token khusus template chat ditangani. Jika backend mentokenisasi string literal -seperti `<|im_start|>`, `<|start_header_id|>`, atau `` sebagai -token template chat struktural di dalam konten pengguna, teks tidak tepercaya dapat mencoba -memalsukan batas peran pada lapisan tokenizer. +Backend yang di-host sendiri dan kompatibel dengan OpenAI seperti vLLM, SGLang, TGI, LM Studio, +atau stack tokenizer Hugging Face khusus dapat berbeda dari penyedia yang di-host dalam cara +token khusus chat-template ditangani. Jika backend melakukan tokenisasi string literal +seperti `<|im_start| -OpenClaw menghapus literal token khusus keluarga model umum dari konten -eksternal yang dibungkus sebelum mengirimkannya ke model. Biarkan pembungkus konten eksternal -tetap aktif, dan utamakan pengaturan backend yang memecah atau meng-escape token khusus -dalam konten yang disediakan pengguna jika tersedia. Penyedia hosted seperti OpenAI -dan Anthropic sudah menerapkan sanitisasi sisi permintaan mereka sendiri. +OpenClaw menghapus literal token khusus umum keluarga model dari konten eksternal yang dibungkus sebelum mengirimkannya ke model. Biarkan pembungkusan konten eksternal tetap aktif, dan utamakan pengaturan backend yang memisahkan atau meng-escape token khusus dalam konten yang disediakan pengguna jika tersedia. Penyedia ter-hosting seperti OpenAI dan Anthropic sudah menerapkan sanitasi sisi permintaan mereka sendiri. ### Kekuatan model (catatan keamanan) Ketahanan terhadap injeksi prompt **tidak** seragam di seluruh tingkat model. Model yang lebih kecil/lebih murah umumnya lebih rentan terhadap penyalahgunaan alat dan pembajakan instruksi, terutama di bawah prompt adversarial. -Untuk agen yang mengaktifkan alat atau agen yang membaca konten tidak tepercaya, risiko injeksi prompt dengan model lama/lebih kecil sering kali terlalu tinggi. Jangan jalankan workload tersebut pada tingkat model yang lemah. +Untuk agen yang mendukung alat atau agen yang membaca konten tidak tepercaya, risiko injeksi prompt dengan model lama/lebih kecil sering kali terlalu tinggi. Jangan jalankan beban kerja tersebut pada tingkat model yang lemah. Rekomendasi: - **Gunakan model generasi terbaru dengan tingkat terbaik** untuk bot apa pun yang dapat menjalankan alat atau menyentuh file/jaringan. -- **Jangan gunakan tingkat lama/lemah/lebih kecil** untuk agen yang mengaktifkan alat atau inbox tidak tepercaya; risiko injeksi prompt terlalu tinggi. -- Jika Anda harus menggunakan model yang lebih kecil, **kurangi radius dampak** (alat read-only, sandboxing kuat, akses filesystem minimal, daftar izin ketat). +- **Jangan gunakan tingkat lama/lebih lemah/lebih kecil** untuk agen yang mendukung alat atau kotak masuk tidak tepercaya; risiko injeksi prompt terlalu tinggi. +- Jika Anda harus menggunakan model yang lebih kecil, **kurangi blast radius** (alat hanya-baca, sandboxing kuat, akses sistem file minimal, allowlist ketat). - Saat menjalankan model kecil, **aktifkan sandboxing untuk semua sesi** dan **nonaktifkan web_search/web_fetch/browser** kecuali input dikontrol secara ketat. -- Untuk asisten pribadi chat-only dengan input tepercaya dan tanpa alat, model yang lebih kecil biasanya baik-baik saja. +- Untuk asisten pribadi khusus chat dengan input tepercaya dan tanpa alat, model yang lebih kecil biasanya tidak masalah. -## Reasoning dan keluaran verbose di grup +## Penalaran dan keluaran verbose di grup -`/reasoning`, `/verbose`, dan `/trace` dapat mengekspos reasoning internal, keluaran alat, -atau diagnostik plugin yang -tidak dimaksudkan untuk channel publik. Dalam pengaturan grup, perlakukan sebagai **debug -saja** dan biarkan nonaktif kecuali Anda secara eksplisit membutuhkannya. +`/reasoning`, `/verbose`, dan `/trace` dapat mengekspos penalaran internal, keluaran alat, atau diagnostik Plugin yang tidak ditujukan untuk kanal publik. Dalam pengaturan grup, perlakukan semuanya sebagai **debug saja** dan biarkan nonaktif kecuali Anda secara eksplisit membutuhkannya. Panduan: -- Biarkan `/reasoning`, `/verbose`, dan `/trace` nonaktif di ruang publik. +- Biarkan `/reasoning`, `/verbose`, dan `/trace` dinonaktifkan di ruang publik. - Jika Anda mengaktifkannya, lakukan hanya di DM tepercaya atau ruang yang dikontrol ketat. -- Ingat: keluaran verbose dan trace dapat menyertakan argumen alat, URL, diagnostik plugin, dan data yang dilihat model. +- Ingat: keluaran verbose dan trace dapat mencakup argumen alat, URL, diagnostik Plugin, dan data yang dilihat model. ## Contoh pengerasan konfigurasi ### Izin file -Jaga config + state tetap privat pada host gateway: +Jaga config + state tetap privat di host Gateway: - `~/.openclaw/openclaw.json`: `600` (hanya baca/tulis pengguna) - `~/.openclaw`: `700` (hanya pengguna) @@ -725,322 +717,241 @@ Jaga config + state tetap privat pada host gateway: Gateway memultipleks **WebSocket + HTTP** pada satu port: - Default: `18789` -- Config/flag/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` +- Konfigurasi/flag/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` -Permukaan HTTP ini mencakup Control UI dan host canvas: +Permukaan HTTP ini mencakup UI Kontrol dan host canvas: -- Control UI (aset SPA) (path dasar default `/`) +- UI Kontrol (aset SPA) (path dasar default `/`) - Host canvas: `/__openclaw__/canvas/` dan `/__openclaw__/a2ui/` (HTML/JS arbitrer; perlakukan sebagai konten tidak tepercaya) Jika Anda memuat konten canvas di browser normal, perlakukan seperti halaman web tidak tepercaya lainnya: -- Jangan paparkan host canvas ke jaringan/pengguna tidak tepercaya. -- Jangan buat konten canvas berbagi origin yang sama dengan permukaan web berprivilege kecuali Anda sepenuhnya memahami implikasinya. +- Jangan paparkan host canvas ke jaringan/pengguna yang tidak tepercaya. +- Jangan buat konten canvas berbagi origin yang sama dengan permukaan web istimewa kecuali Anda sepenuhnya memahami implikasinya. Mode bind mengontrol tempat Gateway mendengarkan: - `gateway.bind: "loopback"` (default): hanya klien lokal yang dapat terhubung. -- Bind non-loopback (`"lan"`, `"tailnet"`, `"custom"`) memperluas permukaan serangan. Gunakan hanya dengan auth gateway (token/password bersama atau proxy tepercaya yang dikonfigurasi dengan benar) dan firewall nyata. +- Bind non-loopback (`"lan"`, `"tailnet"`, `"custom"`) memperluas permukaan serangan. Gunakan hanya dengan autentikasi Gateway (token/kata sandi bersama atau proxy tepercaya yang dikonfigurasi dengan benar) dan firewall nyata. Aturan praktis: - Utamakan Tailscale Serve daripada bind LAN (Serve menjaga Gateway tetap pada loopback, dan Tailscale menangani akses). -- Jika Anda harus bind ke LAN, firewall port ke daftar izin IP sumber yang ketat; jangan port-forward secara luas. -- Jangan pernah mengekspos Gateway tanpa autentikasi pada `0.0.0.0`. +- Jika Anda harus melakukan bind ke LAN, batasi port dengan firewall ke allowlist IP sumber yang ketat; jangan port-forward secara luas. +- Jangan pernah memaparkan Gateway tanpa autentikasi pada `0.0.0.0`. ### Publikasi port Docker dengan UFW -Jika Anda menjalankan OpenClaw dengan Docker di VPS, ingat bahwa port kontainer yang dipublikasikan +Jika Anda menjalankan OpenClaw dengan Docker pada VPS, ingat bahwa port kontainer yang dipublikasikan (`-p HOST:CONTAINER` atau Compose `ports:`) dirutekan melalui chain forwarding Docker, bukan hanya aturan `INPUT` host. -Agar lalu lintas Docker selaras dengan kebijakan firewall Anda, terapkan aturan di -`DOCKER-USER` (chain ini dievaluasi sebelum aturan accept milik Docker sendiri). +Agar lalu lintas Docker tetap selaras dengan kebijakan firewall Anda, terapkan aturan di +`DOCKER-USER` (chain ini dievaluasi sebelum aturan accept milik Docker). Pada banyak distro modern, `iptables`/`ip6tables` menggunakan frontend `iptables-nft` dan tetap menerapkan aturan ini ke backend nftables. -Contoh daftar izin minimal (IPv4): - -```bash -# /etc/ufw/after.rules (append as its own *filter section) -*filter -:DOCKER-USER - [0:0] --A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN --A DOCKER-USER -s 127.0.0.0/8 -j RETURN --A DOCKER-USER -s 10.0.0.0/8 -j RETURN --A DOCKER-USER -s 172.16.0.0/12 -j RETURN --A DOCKER-USER -s 192.168.0.0/16 -j RETURN --A DOCKER-USER -s 100.64.0.0/10 -j RETURN --A DOCKER-USER -p tcp --dport 80 -j RETURN --A DOCKER-USER -p tcp --dport 443 -j RETURN --A DOCKER-USER -m conntrack --ctstate NEW -j DROP --A DOCKER-USER -j RETURN -COMMIT -``` - +Contoh allowlist minimal (IPv4): +__OC_I18N_900008__ IPv6 memiliki tabel terpisah. Tambahkan kebijakan yang sesuai di `/etc/ufw/after6.rules` jika Docker IPv6 diaktifkan. -Hindari hardcoding nama interface seperti `eth0` dalam cuplikan docs. Nama interface -berbeda-beda di berbagai image VPS (`ens3`, `enp*`, dll.) dan ketidakcocokan dapat secara tidak sengaja +Hindari hardcoding nama antarmuka seperti `eth0` dalam cuplikan dokumentasi. Nama antarmuka +bervariasi antar image VPS (`ens3`, `enp*`, dll.) dan ketidakcocokan dapat secara tidak sengaja melewati aturan deny Anda. Validasi cepat setelah reload: - -```bash -ufw reload -iptables -S DOCKER-USER -ip6tables -S DOCKER-USER -nmap -sT -p 1-65535 --open -``` - -Port eksternal yang diharapkan seharusnya hanya yang sengaja Anda ekspos (untuk sebagian besar +__OC_I18N_900009__ +Port eksternal yang diharapkan seharusnya hanya yang sengaja Anda paparkan (untuk sebagian besar setup: SSH + port reverse proxy Anda). ### Penemuan mDNS/Bonjour -Gateway menyiarkan keberadaannya melalui mDNS (`_openclaw-gw._tcp` pada port 5353) untuk penemuan perangkat lokal. Dalam mode penuh, ini mencakup record TXT yang dapat mengekspos detail operasional: +Gateway menyiarkan keberadaannya melalui mDNS (`_openclaw-gw._tcp` pada port 5353) untuk penemuan perangkat lokal. Dalam mode penuh, ini mencakup record TXT yang dapat memaparkan detail operasional: -- `cliPath`: jalur filesystem lengkap ke biner CLI (mengungkap nama pengguna dan lokasi instalasi) +- `cliPath`: path sistem berkas lengkap ke biner CLI (mengungkap nama pengguna dan lokasi instalasi) - `sshPort`: mengiklankan ketersediaan SSH pada host - `displayName`, `lanHost`: informasi nama host -**Pertimbangan keamanan operasional:** Menyiarkan detail infrastruktur mempermudah pengintaian bagi siapa pun di jaringan lokal. Bahkan info yang "tidak berbahaya" seperti jalur filesystem dan ketersediaan SSH membantu penyerang memetakan lingkungan Anda. +**Pertimbangan keamanan operasional:** Menyiarkan detail infrastruktur mempermudah pengintaian bagi siapa pun di jaringan lokal. Bahkan informasi yang "tidak berbahaya" seperti path sistem berkas dan ketersediaan SSH membantu penyerang memetakan lingkungan Anda. **Rekomendasi:** -1. **Mode minimal** (default, direkomendasikan untuk gateway yang terekspos): hilangkan kolom sensitif dari siaran mDNS: - - ```json5 - { - discovery: { - mdns: { mode: "minimal" }, - }, - } - ``` - +1. **Mode minimal** (default, direkomendasikan untuk gateway yang terekspos): hilangkan field sensitif dari siaran mDNS: +__OC_I18N_900010__ 2. **Nonaktifkan sepenuhnya** jika Anda tidak memerlukan penemuan perangkat lokal: +__OC_I18N_900011__ +3. **Mode penuh** (ikut serta): sertakan `cliPath` + `sshPort` dalam catatan TXT: +__OC_I18N_900012__ +4. **Variabel lingkungan** (alternatif): atur `OPENCLAW_DISABLE_BONJOUR=1` untuk menonaktifkan mDNS tanpa perubahan konfigurasi. - ```json5 - { - discovery: { - mdns: { mode: "off" }, - }, - } - ``` - -3. **Mode penuh** (opt-in): sertakan `cliPath` + `sshPort` dalam catatan TXT: - - ```json5 - { - discovery: { - mdns: { mode: "full" }, - }, - } - ``` - -4. **Variabel lingkungan** (alternatif): tetapkan `OPENCLAW_DISABLE_BONJOUR=1` untuk menonaktifkan mDNS tanpa perubahan konfigurasi. - -Dalam mode minimal, Gateway tetap menyiarkan cukup informasi untuk penemuan perangkat (`role`, `gatewayPort`, `transport`) tetapi menghilangkan `cliPath` dan `sshPort`. Aplikasi yang memerlukan informasi jalur CLI dapat mengambilnya melalui koneksi WebSocket terautentikasi sebagai gantinya. +Dalam mode minimal, Gateway tetap menyiarkan informasi yang cukup untuk penemuan perangkat (`role`, `gatewayPort`, `transport`) tetapi menghilangkan `cliPath` dan `sshPort`. Aplikasi yang memerlukan informasi path CLI dapat mengambilnya melalui koneksi WebSocket terautentikasi sebagai gantinya. ### Kunci WebSocket Gateway (auth lokal) -Auth Gateway **diwajibkan secara default**. Jika tidak ada jalur auth gateway valid yang dikonfigurasi, -Gateway menolak koneksi WebSocket (gagal-tertutup). +Auth Gateway **diwajibkan secara default**. Jika tidak ada path auth gateway valid yang dikonfigurasi, +Gateway menolak koneksi WebSocket (gagal tertutup). Onboarding menghasilkan token secara default (bahkan untuk loopback) sehingga klien lokal harus melakukan autentikasi. -Tetapkan token agar **semua** klien WS harus melakukan autentikasi: - -```json5 -{ - gateway: { - auth: { mode: "token", token: "your-token" }, - }, -} -``` - +Atur token agar **semua** klien WS harus melakukan autentikasi: +__OC_I18N_900013__ Doctor dapat membuatkannya untuk Anda: `openclaw doctor --generate-gateway-token`. -`gateway.remote.token` dan `gateway.remote.password` adalah sumber kredensial klien. Keduanya **tidak** melindungi akses WS lokal dengan sendirinya. Jalur panggilan lokal dapat menggunakan `gateway.remote.*` sebagai fallback hanya ketika `gateway.auth.*` belum ditetapkan. Jika `gateway.auth.token` atau `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak terselesaikan, resolusi gagal tertutup (tidak ada fallback jarak jauh yang menutupinya). +`gateway.remote.token` dan `gateway.remote.password` adalah sumber kredensial klien. Keduanya **tidak** melindungi akses WS lokal dengan sendirinya. Path panggilan lokal dapat menggunakan `gateway.remote.*` sebagai fallback hanya ketika `gateway.auth.*` tidak diatur. Jika `gateway.auth.token` atau `gateway.auth.password` dikonfigurasi secara eksplisit melalui SecretRef dan tidak terselesaikan, resolusi gagal tertutup (tidak ada fallback jarak jauh yang menutupi). Opsional: pin TLS jarak jauh dengan `gateway.remote.tlsFingerprint` saat menggunakan `wss://`. -Plaintext `ws://` secara default hanya untuk loopback. Untuk jalur jaringan privat -tepercaya, tetapkan `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` pada proses klien sebagai +Teks polos `ws://` secara default hanya untuk loopback. Untuk path jaringan privat +tepercaya, atur `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` pada proses klien sebagai akses darurat. Ini sengaja hanya berupa lingkungan proses, bukan kunci konfigurasi `openclaw.json`. -Pairing seluler dan rute gateway manual atau hasil pemindaian Android lebih ketat: -cleartext diterima untuk loopback, tetapi private-LAN, link-local, `.local`, dan -nama host tanpa titik harus menggunakan TLS kecuali Anda secara eksplisit memilih jalur cleartext -jaringan privat tepercaya. +Pemasangan seluler dan rute gateway manual atau hasil pindai Android lebih ketat: +teks jelas diterima untuk loopback, tetapi host private-LAN, link-local, `.local`, dan +nama host tanpa titik harus menggunakan TLS kecuali Anda secara eksplisit memilih +jalur teks jelas jaringan privat tepercaya. -Pairing perangkat lokal: +Pemasangan perangkat lokal: -- Pairing perangkat disetujui otomatis untuk koneksi local loopback langsung agar - klien pada host yang sama tetap lancar. -- OpenClaw juga memiliki jalur self-connect backend/container-lokal yang sempit untuk - alur helper shared-secret tepercaya. -- Koneksi tailnet dan LAN, termasuk bind tailnet pada host yang sama, diperlakukan sebagai - jarak jauh untuk pairing dan tetap memerlukan persetujuan. -- Bukti forwarded-header pada permintaan loopback membatalkan lokalitas - loopback. Persetujuan otomatis metadata-upgrade memiliki cakupan sempit. Lihat - [Pairing Gateway](/id/gateway/pairing) untuk kedua aturan tersebut. +- Pemasangan perangkat disetujui otomatis untuk koneksi direct local loopback agar + klien host yang sama tetap mulus. +- OpenClaw juga memiliki path self-connect backend/container-lokal yang sempit untuk + alur helper rahasia bersama tepercaya. +- Koneksi tailnet dan LAN, termasuk bind tailnet host yang sama, diperlakukan sebagai + jarak jauh untuk pemasangan dan tetap memerlukan persetujuan. +- Bukti header yang diteruskan pada permintaan loopback mendiskualifikasi lokalitas + loopback. Persetujuan otomatis peningkatan metadata dibatasi secara sempit. Lihat + [pemasangan Gateway](/gateway/pairing) untuk kedua aturan. Mode auth: - `gateway.auth.mode: "token"`: token bearer bersama (direkomendasikan untuk sebagian besar setup). -- `gateway.auth.mode: "password"`: auth kata sandi (lebih baik ditetapkan melalui env: `OPENCLAW_GATEWAY_PASSWORD`). -- `gateway.auth.mode: "trusted-proxy"`: percayai reverse proxy sadar-identitas untuk mengautentikasi pengguna dan meneruskan identitas melalui header (lihat [Auth Proxy Tepercaya](/id/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "password"`: auth kata sandi (lebih baik diatur melalui env: `OPENCLAW_GATEWAY_PASSWORD`). +- `gateway.auth.mode: "trusted-proxy"`: percayai proxy balik yang sadar identitas untuk mengautentikasi pengguna dan meneruskan identitas melalui header (lihat [Auth Proxy Tepercaya](/gateway/trusted-proxy-auth)). -Checklist rotasi (token/kata sandi): +Daftar periksa rotasi (token/kata sandi): -1. Buat/tetapkan rahasia baru (`gateway.auth.token` atau `OPENCLAW_GATEWAY_PASSWORD`). +1. Buat/atur secret baru (`gateway.auth.token` atau `OPENCLAW_GATEWAY_PASSWORD`). 2. Mulai ulang Gateway (atau mulai ulang aplikasi macOS jika aplikasi tersebut mengawasi Gateway). 3. Perbarui klien jarak jauh apa pun (`gateway.remote.token` / `.password` pada mesin yang memanggil ke Gateway). -4. Verifikasi Anda tidak lagi dapat terhubung dengan kredensial lama. +4. Verifikasi bahwa Anda tidak lagi dapat terhubung dengan kredensial lama. ### Header identitas Tailscale Serve Ketika `gateway.auth.allowTailscale` bernilai `true` (default untuk Serve), OpenClaw -menerima header identitas Tailscale Serve (`tailscale-user-login`) untuk autentikasi Control -UI/WebSocket. OpenClaw memverifikasi identitas dengan menyelesaikan alamat +menerima header identitas Tailscale Serve (`tailscale-user-login`) untuk autentikasi +UI/WebSocket Kontrol. OpenClaw memverifikasi identitas dengan menyelesaikan alamat `x-forwarded-for` melalui daemon Tailscale lokal (`tailscale whois`) -dan mencocokkannya dengan header. Ini hanya terpicu untuk permintaan yang mengenai loopback +dan mencocokkannya dengan header. Ini hanya dipicu untuk permintaan yang mengenai loopback dan menyertakan `x-forwarded-for`, `x-forwarded-proto`, dan `x-forwarded-host` seperti -yang disuntikkan oleh Tailscale. -Untuk jalur pemeriksaan identitas async ini, upaya gagal untuk `{scope, ip}` yang sama -diserialkan sebelum limiter mencatat kegagalan. Retry buruk yang serentak -dari satu klien Serve karena itu dapat mengunci upaya kedua seketika -alih-alih berpacu sebagai dua mismatch biasa. +yang disisipkan oleh Tailscale. +Untuk path pemeriksaan identitas async ini, upaya gagal untuk `{scope, ip}` yang sama +diserialisasi sebelum pembatas mencatat kegagalan. Karena itu, percobaan ulang buruk yang konkuren +dari satu klien Serve dapat langsung mengunci upaya kedua +alih-alih berpacu sebagai dua ketidakcocokan biasa. Endpoint HTTP API (misalnya `/v1/*`, `/tools/invoke`, dan `/api/channels/*`) -**tidak** menggunakan auth header identitas Tailscale. Endpoint tersebut tetap mengikuti mode auth HTTP -yang dikonfigurasi gateway. +**tidak** menggunakan auth header-identitas Tailscale. Endpoint tersebut tetap mengikuti mode +auth HTTP yang dikonfigurasi gateway. Catatan batas penting: - Auth bearer HTTP Gateway pada dasarnya adalah akses operator semua-atau-tidak-sama-sekali. -- Perlakukan kredensial yang dapat memanggil `/v1/chat/completions`, `/v1/responses`, atau `/api/channels/*` sebagai rahasia operator akses penuh untuk gateway tersebut. -- Pada permukaan HTTP kompatibel OpenAI, auth bearer shared-secret memulihkan seluruh cakupan operator default (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) dan semantik pemilik untuk giliran agent; nilai `x-openclaw-scopes` yang lebih sempit tidak mengurangi jalur shared-secret tersebut. -- Semantik cakupan per permintaan pada HTTP hanya berlaku ketika permintaan berasal dari mode yang membawa identitas seperti auth trusted proxy atau `gateway.auth.mode="none"` pada ingress privat. -- Dalam mode yang membawa identitas tersebut, menghilangkan `x-openclaw-scopes` kembali ke set cakupan default operator normal; kirim header secara eksplisit saat Anda menginginkan set cakupan yang lebih sempit. -- `/tools/invoke` mengikuti aturan shared-secret yang sama: auth bearer token/kata sandi juga diperlakukan sebagai akses operator penuh di sana, sementara mode yang membawa identitas tetap menghormati cakupan yang dideklarasikan. +- Perlakukan kredensial yang dapat memanggil `/v1/chat/completions`, `/v1/responses`, atau `/api/channels/*` sebagai secret operator akses penuh untuk gateway tersebut. +- Pada permukaan HTTP yang kompatibel dengan OpenAI, auth bearer rahasia bersama memulihkan seluruh scope operator default (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) dan semantik pemilik untuk giliran agen; nilai `x-openclaw-scopes` yang lebih sempit tidak mengurangi path rahasia bersama tersebut. +- Semantik scope per permintaan pada HTTP hanya berlaku ketika permintaan berasal dari mode yang membawa identitas seperti auth proxy tepercaya atau `gateway.auth.mode="none"` pada ingress privat. +- Dalam mode yang membawa identitas tersebut, menghilangkan `x-openclaw-scopes` akan fallback ke set scope default operator normal; kirim header secara eksplisit saat Anda menginginkan set scope yang lebih sempit. +- `/tools/invoke` mengikuti aturan rahasia bersama yang sama: auth bearer token/kata sandi juga diperlakukan sebagai akses operator penuh di sana, sementara mode yang membawa identitas tetap menghormati scope yang dideklarasikan. - Jangan bagikan kredensial ini dengan pemanggil yang tidak tepercaya; lebih baik gunakan gateway terpisah per batas kepercayaan. **Asumsi kepercayaan:** auth Serve tanpa token mengasumsikan host gateway tepercaya. -Jangan perlakukan ini sebagai perlindungan terhadap proses pada host yang sama yang bermusuhan. Jika kode lokal yang tidak tepercaya -mungkin berjalan pada host gateway, nonaktifkan `gateway.auth.allowTailscale` -dan wajibkan auth shared-secret eksplisit dengan `gateway.auth.mode: "token"` atau +Jangan perlakukan ini sebagai perlindungan terhadap proses host yang sama yang bermusuhan. Jika kode lokal +tidak tepercaya dapat berjalan pada host gateway, nonaktifkan `gateway.auth.allowTailscale` +dan wajibkan auth rahasia bersama eksplisit dengan `gateway.auth.mode: "token"` atau `"password"`. -**Aturan keamanan:** jangan teruskan header ini dari reverse proxy Anda sendiri. Jika -Anda menghentikan TLS atau melakukan proxy di depan gateway, nonaktifkan -`gateway.auth.allowTailscale` dan gunakan auth shared-secret (`gateway.auth.mode: -"token"` atau `"password"`) atau [Auth Proxy Tepercaya](/id/gateway/trusted-proxy-auth) +**Aturan keamanan:** jangan teruskan header ini dari proxy balik Anda sendiri. Jika +Anda mengakhiri TLS atau melakukan proxy di depan gateway, nonaktifkan +`gateway.auth.allowTailscale` dan gunakan auth rahasia bersama (`gateway.auth.mode: +"token"` atau `"password"`) atau [Auth Proxy Tepercaya](/gateway/trusted-proxy-auth) sebagai gantinya. Proxy tepercaya: -- Jika Anda menghentikan TLS di depan Gateway, tetapkan `gateway.trustedProxies` ke IP proxy Anda. -- OpenClaw akan memercayai `x-forwarded-for` (atau `x-real-ip`) dari IP tersebut untuk menentukan IP klien bagi pemeriksaan pairing lokal dan auth HTTP/pemeriksaan lokal. +- Jika Anda mengakhiri TLS di depan Gateway, atur `gateway.trustedProxies` ke IP proxy Anda. +- OpenClaw akan mempercayai `x-forwarded-for` (atau `x-real-ip`) dari IP tersebut untuk menentukan IP klien bagi pemeriksaan pemasangan lokal dan pemeriksaan auth/lokal HTTP. - Pastikan proxy Anda **menimpa** `x-forwarded-for` dan memblokir akses langsung ke port Gateway. -Lihat [Tailscale](/id/gateway/tailscale) dan [Ikhtisar web](/id/web). +Lihat [Tailscale](/gateway/tailscale) dan [ikhtisar Web](/web). -### Kontrol browser melalui host Node (direkomendasikan) +### Kontrol browser melalui host node (direkomendasikan) -Jika Gateway Anda jarak jauh tetapi browser berjalan di mesin lain, jalankan **host Node** -pada mesin browser dan biarkan Gateway mem-proxy tindakan browser (lihat [Alat browser](/id/tools/browser)). -Perlakukan pairing Node seperti akses admin. +Jika Gateway Anda jarak jauh tetapi browser berjalan pada mesin lain, jalankan **host node** +pada mesin browser dan biarkan Gateway mem-proxy aksi browser (lihat [alat Browser](/tools/browser)). +Perlakukan pemasangan node seperti akses admin. Pola yang direkomendasikan: -- Pertahankan Gateway dan host Node pada tailnet yang sama (Tailscale). -- Pairing Node secara sengaja; nonaktifkan routing proxy browser jika Anda tidak memerlukannya. +- Jaga Gateway dan host node berada pada tailnet yang sama (Tailscale). +- Pasangkan node secara sengaja; nonaktifkan perutean proxy browser jika Anda tidak membutuhkannya. Hindari: - Mengekspos port relay/kontrol melalui LAN atau Internet publik. - Tailscale Funnel untuk endpoint kontrol browser (eksposur publik). -### Rahasia di disk +### Secret di disk -Anggap apa pun di bawah `~/.openclaw/` (atau `$OPENCLAW_STATE_DIR/`) dapat berisi rahasia atau data privat: +Asumsikan apa pun di bawah `~/.openclaw/` (atau `$OPENCLAW_STATE_DIR/`) dapat berisi secret atau data privat: - `openclaw.json`: konfigurasi dapat menyertakan token (gateway, gateway jarak jauh), pengaturan provider, dan allowlist. -- `credentials/**`: kredensial channel (contoh: kredensial WhatsApp), allowlist pairing, impor OAuth lama. +- `credentials/**`: kredensial channel (contoh: kredensial WhatsApp), allowlist pemasangan, impor OAuth lama. - `agents//agent/auth-profiles.json`: kunci API, profil token, token OAuth, dan `keyRef`/`tokenRef` opsional. -- `secrets.json` (opsional): payload rahasia berbasis file yang digunakan oleh provider SecretRef `file` (`secrets.providers`). -- `agents//agent/auth.json`: file kompatibilitas lama. Entri `api_key` statis dihapus saat ditemukan. -- `agents//sessions/**`: transkrip sesi (`*.jsonl`) + metadata routing (`sessions.json`) yang dapat berisi pesan privat dan output alat. -- paket Plugin bawaan: Plugin yang terinstal (beserta `node_modules/`-nya). +- `agents//agent/codex-home/**`: akun app-server Codex per agen, konfigurasi, Skills, plugin, status thread native, dan diagnostik. +- `secrets.json` (opsional): payload secret berbasis file yang digunakan oleh provider SecretRef `file` (`secrets.providers`). +- `agents//agent/auth.json`: file kompatibilitas lama. Entri `api_key` statis dibersihkan saat ditemukan. +- `agents//sessions/**`: transkrip sesi (`*.jsonl`) + metadata perutean (`sessions.json`) yang dapat berisi pesan privat dan output alat. +- paket Plugin bawaan: Plugin yang terinstal (plus `node_modules/` miliknya). - `sandboxes/**`: workspace sandbox alat; dapat mengakumulasi salinan file yang Anda baca/tulis di dalam sandbox. -Tips pengerasan: +Tips penguatan: - Jaga izin tetap ketat (`700` pada direktori, `600` pada file). -- Gunakan enkripsi disk penuh pada host gateway. -- Lebih baik gunakan akun pengguna OS khusus untuk Gateway jika host digunakan bersama. +- Gunakan enkripsi seluruh disk pada host gateway. +- Lebih baik gunakan akun pengguna OS khusus untuk Gateway jika host dibagikan. ### File `.env` workspace -OpenClaw memuat file `.env` lokal-workspace untuk agent dan alat, tetapi tidak pernah membiarkan file tersebut diam-diam mengganti kontrol runtime gateway. +OpenClaw memuat file `.env` lokal-workspace untuk agen dan alat, tetapi tidak pernah membiarkan file tersebut menimpa kontrol runtime gateway secara diam-diam. - Kunci apa pun yang dimulai dengan `OPENCLAW_*` diblokir dari file `.env` workspace yang tidak tepercaya. -- Pengaturan endpoint channel untuk Matrix, Mattermost, IRC, dan Synology Chat juga diblokir dari override `.env` workspace, sehingga workspace hasil clone tidak dapat mengalihkan traffic connector bawaan melalui konfigurasi endpoint lokal. Kunci env endpoint (seperti `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) harus berasal dari lingkungan proses gateway atau `env.shellEnv`, bukan dari `.env` yang dimuat dari workspace. -- Pemblokiran ini bersifat gagal-tertutup: variabel kontrol-runtime baru yang ditambahkan dalam rilis mendatang tidak dapat diwarisi dari `.env` yang masuk repo atau disediakan penyerang; kunci diabaikan dan gateway mempertahankan nilainya sendiri. -- Variabel lingkungan proses/OS tepercaya (shell gateway sendiri, unit launchd/systemd, app bundle) tetap berlaku — ini hanya membatasi pemuatan file `.env`. +- Pengaturan endpoint channel untuk Matrix, Mattermost, IRC, dan Synology Chat juga diblokir dari override `.env` workspace, sehingga workspace hasil kloning tidak dapat mengarahkan traffic konektor bawaan melalui konfigurasi endpoint lokal. Kunci env endpoint (seperti `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) harus berasal dari lingkungan proses gateway atau `env.shellEnv`, bukan dari `.env` yang dimuat workspace. +- Pemblokiran ini gagal tertutup: variabel kontrol runtime baru yang ditambahkan dalam rilis mendatang tidak dapat diwarisi dari `.env` yang di-check-in atau disuplai penyerang; kunci diabaikan dan gateway mempertahankan nilainya sendiri. +- Variabel lingkungan proses/OS tepercaya (shell milik gateway, unit launchd/systemd, bundel aplikasi) tetap berlaku — ini hanya membatasi pemuatan file `.env`. -Alasan: file `.env` workspace sering berada di sebelah kode agent, tidak sengaja di-commit, atau ditulis oleh alat. Memblokir seluruh prefiks `OPENCLAW_*` berarti menambahkan flag `OPENCLAW_*` baru nanti tidak pernah dapat mengalami regresi menjadi pewarisan diam-diam dari state workspace. +Alasannya: file `.env` workspace sering berada di sebelah kode agen, ter-commit secara tidak sengaja, atau ditulis oleh alat. Memblokir seluruh prefiks `OPENCLAW_*` berarti penambahan flag `OPENCLAW_*` baru nanti tidak pernah dapat mengalami regresi menjadi pewarisan diam-diam dari status workspace. ### Log dan transkrip (redaksi dan retensi) Log dan transkrip dapat membocorkan info sensitif bahkan ketika kontrol akses sudah benar: - Log Gateway dapat menyertakan ringkasan alat, error, dan URL. -- Transkrip sesi dapat menyertakan rahasia yang ditempel, isi file, output perintah, dan tautan. +- Transkrip sesi dapat menyertakan secret yang ditempel, isi file, output perintah, dan tautan. Rekomendasi: - Biarkan redaksi log dan transkrip aktif (`logging.redactSensitive: "tools"`; default). - Tambahkan pola khusus untuk lingkungan Anda melalui `logging.redactPatterns` (token, nama host, URL internal). -- Saat membagikan diagnostik, lebih baik gunakan `openclaw status --all` (dapat ditempel, rahasia direduksi) daripada log mentah. -- Pangkas transkrip sesi dan file log lama jika Anda tidak memerlukan retensi panjang. +- Saat berbagi diagnostik, lebih baik gunakan `openclaw status --all` (dapat ditempel, secret diredaksi) daripada log mentah. +- Pangkas transkrip sesi lama dan file log jika Anda tidak memerlukan retensi panjang. -Detail: [Logging](/id/gateway/logging) +Detail: [Logging](/gateway/logging) -### DM: pairing secara default - -```json5 -{ - channels: { whatsapp: { dmPolicy: "pairing" } }, -} -``` - -### Grup: wajibkan mention di mana saja - -```json -{ - "channels": { - "whatsapp": { - "groups": { - "*": { "requireMention": true } - } - } - }, - "agents": { - "list": [ - { - "id": "main", - "groupChat": { "mentionPatterns": ["@openclaw", "@mybot"] } - } - ] - } -} -``` - -Dalam chat grup, hanya respons saat disebut secara eksplisit. +### DM: pemasangan secara default +__OC_I18N_900014__ +### Grup: wajibkan mention di mana-mana +__OC_I18N_900015__ +Dalam chat grup, hanya respons saat disebutkan secara eksplisit. ### Nomor terpisah (WhatsApp, Signal, Telegram) @@ -1049,281 +960,159 @@ Untuk channel berbasis nomor telepon, pertimbangkan menjalankan AI Anda pada nom - Nomor pribadi: Percakapan Anda tetap privat - Nomor bot: AI menangani ini, dengan batasan yang sesuai -### Mode hanya-baca (melalui sandbox dan tools) +### Mode baca saja (melalui sandbox dan tools) -Anda dapat membuat profil hanya-baca dengan menggabungkan: +Anda dapat membuat profil baca saja dengan menggabungkan: - `agents.defaults.sandbox.workspaceAccess: "ro"` (atau `"none"` untuk tanpa akses workspace) -- daftar izin/tolak tool yang memblokir `write`, `edit`, `apply_patch`, `exec`, `process`, dll. +- daftar izinkan/tolak tool yang memblokir `write`, `edit`, `apply_patch`, `exec`, `process`, dll. Opsi pengerasan tambahan: -- `tools.exec.applyPatch.workspaceOnly: true` (default): memastikan `apply_patch` tidak dapat menulis/menghapus di luar direktori workspace meskipun sandboxing nonaktif. Atur ke `false` hanya jika Anda memang ingin `apply_patch` menyentuh file di luar workspace. -- `tools.fs.workspaceOnly: true` (opsional): membatasi path `read`/`write`/`edit`/`apply_patch` dan path auto-load gambar prompt native ke direktori workspace (berguna jika saat ini Anda mengizinkan path absolut dan menginginkan satu guardrail). -- Jaga root sistem file tetap sempit: hindari root yang luas seperti direktori home Anda untuk workspace/sandbox workspace agen. Root yang luas dapat mengekspos file lokal sensitif (misalnya state/config di bawah `~/.openclaw`) ke tool sistem file. +- `tools.exec.applyPatch.workspaceOnly: true` (default): memastikan `apply_patch` tidak dapat menulis/menghapus di luar direktori workspace bahkan saat sandboxing dinonaktifkan. Setel ke `false` hanya jika Anda sengaja ingin `apply_patch` menyentuh file di luar workspace. +- `tools.fs.workspaceOnly: true` (opsional): membatasi jalur `read`/`write`/`edit`/`apply_patch` dan jalur muat otomatis gambar prompt native ke direktori workspace (berguna jika Anda mengizinkan jalur absolut saat ini dan menginginkan satu pagar pengaman). +- Jaga root filesystem tetap sempit: hindari root luas seperti direktori home Anda untuk workspace agent/workspace sandbox. Root luas dapat mengekspos file lokal sensitif (misalnya state/config di bawah `~/.openclaw`) ke tool filesystem. ### Baseline aman (salin/tempel) Satu konfigurasi “default aman” yang menjaga Gateway tetap privat, mewajibkan pairing DM, dan menghindari bot grup yang selalu aktif: +__OC_I18N_900016__ +Jika Anda juga menginginkan eksekusi tool yang “lebih aman secara default”, tambahkan sandbox + tolak tool berbahaya untuk agent non-pemilik mana pun (contoh di bawah pada “Profil akses per agent”). -```json5 -{ - gateway: { - mode: "local", - bind: "loopback", - port: 18789, - auth: { mode: "token", token: "your-long-random-token" }, - }, - channels: { - whatsapp: { - dmPolicy: "pairing", - groups: { "*": { requireMention: true } }, - }, - }, -} -``` - -Jika Anda juga menginginkan eksekusi tool yang “lebih aman secara default”, tambahkan sandbox + tolak tool berbahaya untuk agen non-pemilik mana pun (contoh di bawah pada “Profil akses per agen”). - -Baseline bawaan untuk giliran agen berbasis chat: pengirim non-pemilik tidak dapat menggunakan tool `cron` atau `gateway`. +Baseline bawaan untuk giliran agent yang digerakkan chat: pengirim non-pemilik tidak dapat menggunakan tool `cron` atau `gateway`. ## Sandboxing (direkomendasikan) -Dokumen khusus: [Sandboxing](/id/gateway/sandboxing) +Dokumen khusus: [Sandboxing](/gateway/sandboxing) Dua pendekatan yang saling melengkapi: -- **Jalankan Gateway penuh di Docker** (batas container): [Docker](/id/install/docker) -- **Tool sandbox** (`agents.defaults.sandbox`, gateway host + tool yang diisolasi sandbox; Docker adalah backend default): [Sandboxing](/id/gateway/sandboxing) +- **Jalankan Gateway penuh di Docker** (batas container): [Docker](/install/docker) +- **Tool sandbox** (`agents.defaults.sandbox`, host gateway + tool yang diisolasi sandbox; Docker adalah backend default): [Sandboxing](/gateway/sandboxing) -Untuk mencegah akses lintas agen, pertahankan `agents.defaults.sandbox.scope` pada `"agent"` (default) atau `"session"` untuk isolasi per sesi yang lebih ketat. `scope: "shared"` menggunakan satu container atau workspace. +Untuk mencegah akses lintas-agent, pertahankan `agents.defaults.sandbox.scope` pada `"agent"` (default) atau `"session"` untuk isolasi per-sesi yang lebih ketat. `scope: "shared"` menggunakan satu container atau workspace. -Pertimbangkan juga akses workspace agen di dalam sandbox: +Pertimbangkan juga akses workspace agent di dalam sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (default) menjaga workspace agen tetap tidak dapat diakses; tool berjalan terhadap sandbox workspace di bawah `~/.openclaw/sandboxes` -- `agents.defaults.sandbox.workspaceAccess: "ro"` memasang workspace agen sebagai hanya-baca di `/agent` (menonaktifkan `write`/`edit`/`apply_patch`) -- `agents.defaults.sandbox.workspaceAccess: "rw"` memasang workspace agen sebagai baca/tulis di `/workspace` -- `sandbox.docker.binds` tambahan divalidasi terhadap path sumber yang dinormalisasi dan dikanonikalisasi. Trik symlink induk dan alias home kanonik tetap gagal tertutup jika resolve ke root yang diblokir seperti `/etc`, `/var/run`, atau direktori kredensial di bawah home OS. +- `agents.defaults.sandbox.workspaceAccess: "none"` (default) membuat workspace agent tidak dapat diakses; tool berjalan terhadap workspace sandbox di bawah `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "ro"` me-mount workspace agent sebagai baca saja di `/agent` (menonaktifkan `write`/`edit`/`apply_patch`) +- `agents.defaults.sandbox.workspaceAccess: "rw"` me-mount workspace agent sebagai baca/tulis di `/workspace` +- `sandbox.docker.binds` tambahan divalidasi terhadap jalur sumber yang dinormalisasi dan dikanonikalisasi. Trik symlink induk dan alias home kanonis tetap gagal tertutup jika resolve ke root yang diblokir seperti `/etc`, `/var/run`, atau direktori kredensial di bawah home OS. -`tools.elevated` adalah escape hatch baseline global yang menjalankan exec di luar sandbox. Host efektif adalah `gateway` secara default, atau `node` ketika target exec dikonfigurasi ke `node`. Jaga `tools.elevated.allowFrom` tetap ketat dan jangan aktifkan untuk orang asing. Anda dapat membatasi elevated lebih lanjut per agen melalui `agents.list[].tools.elevated`. Lihat [Mode elevated](/id/tools/elevated). +`tools.elevated` adalah celah keluar baseline global yang menjalankan exec di luar sandbox. Host efektif adalah `gateway` secara default, atau `node` saat target exec dikonfigurasi ke `node`. Jaga `tools.elevated.allowFrom` tetap ketat dan jangan aktifkan untuk orang asing. Anda dapat membatasi elevated lebih lanjut per agent melalui `agents.list[].tools.elevated`. Lihat [Mode elevated](/tools/elevated). -### Guardrail delegasi sub-agen +### Pagar pengaman delegasi sub-agent -Jika Anda mengizinkan tool sesi, perlakukan jalannya sub-agen terdelegasi sebagai keputusan batas lain: +Jika Anda mengizinkan tool sesi, perlakukan eksekusi sub-agent yang didelegasikan sebagai keputusan batas lain: -- Tolak `sessions_spawn` kecuali agen benar-benar membutuhkan delegasi. -- Batasi `agents.defaults.subagents.allowAgents` dan override per agen `agents.list[].subagents.allowAgents` apa pun ke agen target yang diketahui aman. -- Untuk workflow apa pun yang harus tetap di-sandbox, panggil `sessions_spawn` dengan `sandbox: "require"` (default adalah `inherit`). -- `sandbox: "require"` gagal cepat ketika runtime anak target tidak di-sandbox. +- Tolak `sessions_spawn` kecuali agent benar-benar membutuhkan delegasi. +- Batasi `agents.defaults.subagents.allowAgents` dan override per-agent `agents.list[].subagents.allowAgents` apa pun ke agent target yang diketahui aman. +- Untuk workflow apa pun yang harus tetap berada dalam sandbox, panggil `sessions_spawn` dengan `sandbox: "require"` (default adalah `inherit`). +- `sandbox: "require"` gagal cepat saat runtime child target tidak berada dalam sandbox. ## Risiko kontrol browser Mengaktifkan kontrol browser memberi model kemampuan untuk mengendalikan browser nyata. -Jika profil browser itu sudah berisi sesi login, model dapat +Jika profil browser tersebut sudah berisi sesi yang login, model dapat mengakses akun dan data tersebut. Perlakukan profil browser sebagai **state sensitif**: -- Lebih pilih profil khusus untuk agen (profil default `openclaw`). -- Hindari mengarahkan agen ke profil pribadi harian Anda. -- Biarkan kontrol browser host tetap nonaktif untuk agen yang di-sandbox kecuali Anda memercayainya. -- API kontrol browser standalone local loopback hanya menghormati autentikasi shared-secret - (auth bearer token gateway atau password gateway). API ini tidak memakai +- Lebih pilih profil khusus untuk agent (profil default `openclaw`). +- Hindari mengarahkan agent ke profil pribadi yang Anda gunakan sehari-hari. +- Biarkan kontrol browser host dinonaktifkan untuk agent dalam sandbox kecuali Anda mempercayainya. +- API kontrol browser local loopback standalone hanya menghormati autentikasi shared-secret + (auth bearer token gateway atau kata sandi gateway). API ini tidak menggunakan header identitas trusted-proxy atau Tailscale Serve. -- Perlakukan unduhan browser sebagai input tidak tepercaya; lebih pilih direktori unduhan yang terisolasi. -- Nonaktifkan sinkronisasi browser/pengelola password di profil agen jika memungkinkan (mengurangi blast radius). -- Untuk gateway jarak jauh, anggap “kontrol browser” setara dengan “akses operator” ke apa pun yang dapat dijangkau profil itu. +- Perlakukan unduhan browser sebagai input tidak tepercaya; lebih pilih direktori unduhan terisolasi. +- Nonaktifkan sinkronisasi browser/pengelola kata sandi di profil agent jika memungkinkan (mengurangi radius dampak). +- Untuk gateway remote, asumsikan “kontrol browser” setara dengan “akses operator” ke apa pun yang dapat dijangkau profil tersebut. - Jaga host Gateway dan node hanya tailnet; hindari mengekspos port kontrol browser ke LAN atau Internet publik. - Nonaktifkan routing proxy browser saat Anda tidak membutuhkannya (`gateway.nodes.browser.mode="off"`). -- Mode sesi-eksisting Chrome MCP **bukan** “lebih aman”; mode ini dapat bertindak sebagai Anda di apa pun yang dapat dijangkau profil Chrome host tersebut. +- Mode sesi yang sudah ada Chrome MCP **bukan** “lebih aman”; mode ini dapat bertindak sebagai Anda pada apa pun yang dapat dijangkau profil Chrome host tersebut. ### Kebijakan SSRF browser (ketat secara default) -Kebijakan navigasi browser OpenClaw bersifat ketat secara default: tujuan privat/internal tetap diblokir kecuali Anda secara eksplisit ikut serta. +Kebijakan navigasi browser OpenClaw ketat secara default: tujuan privat/internal tetap diblokir kecuali Anda secara eksplisit ikut serta. -- Default: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` tidak disetel, sehingga navigasi browser tetap memblokir tujuan privat/internal/penggunaan-khusus. -- Alias legacy: `browser.ssrfPolicy.allowPrivateNetwork` masih diterima untuk kompatibilitas. -- Mode opt-in: setel `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` untuk mengizinkan tujuan privat/internal/penggunaan-khusus. +- Default: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` tidak disetel, sehingga navigasi browser tetap memblokir tujuan privat/internal/special-use. +- Alias lama: `browser.ssrfPolicy.allowPrivateNetwork` masih diterima untuk kompatibilitas. +- Mode ikut serta: setel `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` untuk mengizinkan tujuan privat/internal/special-use. - Dalam mode ketat, gunakan `hostnameAllowlist` (pola seperti `*.example.com`) dan `allowedHostnames` (pengecualian host persis, termasuk nama yang diblokir seperti `localhost`) untuk pengecualian eksplisit. -- Navigasi diperiksa sebelum request dan diperiksa ulang secara best-effort pada URL `http(s)` akhir setelah navigasi untuk mengurangi pivot berbasis redirect. +- Navigasi diperiksa sebelum request dan diperiksa ulang secara best-effort pada URL `http(s)` final setelah navigasi untuk mengurangi pivot berbasis redirect. Contoh kebijakan ketat: +__OC_I18N_900017__ +## Profil akses per agent (multi-agent) -```json5 -{ - browser: { - ssrfPolicy: { - dangerouslyAllowPrivateNetwork: false, - hostnameAllowlist: ["*.example.com", "example.com"], - allowedHostnames: ["localhost"], - }, - }, -} -``` - -## Profil akses per agen (multi-agen) - -Dengan routing multi-agen, setiap agen dapat memiliki sandbox + kebijakan tool sendiri: -gunakan ini untuk memberikan **akses penuh**, **hanya-baca**, atau **tanpa akses** per agen. -Lihat [Sandbox & Tools Multi-Agen](/id/tools/multi-agent-sandbox-tools) untuk detail lengkap +Dengan routing multi-agent, setiap agent dapat memiliki sandbox + kebijakan tool sendiri: +gunakan ini untuk memberikan **akses penuh**, **baca saja**, atau **tanpa akses** per agent. +Lihat [Sandbox & Tools Multi-Agent](/tools/multi-agent-sandbox-tools) untuk detail lengkap dan aturan presedensi. Kasus penggunaan umum: -- Agen pribadi: akses penuh, tanpa sandbox -- Agen keluarga/kerja: sandbox + tool hanya-baca -- Agen publik: sandbox + tanpa tool sistem file/shell +- Agent pribadi: akses penuh, tanpa sandbox +- Agent keluarga/kerja: dalam sandbox + tool baca saja +- Agent publik: dalam sandbox + tanpa tool filesystem/shell ### Contoh: akses penuh (tanpa sandbox) - -```json5 -{ - agents: { - list: [ - { - id: "personal", - workspace: "~/.openclaw/workspace-personal", - sandbox: { mode: "off" }, - }, - ], - }, -} -``` - -### Contoh: tool hanya-baca + workspace hanya-baca - -```json5 -{ - agents: { - list: [ - { - id: "family", - workspace: "~/.openclaw/workspace-family", - sandbox: { - mode: "all", - scope: "agent", - workspaceAccess: "ro", - }, - tools: { - allow: ["read"], - deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], - }, - }, - ], - }, -} -``` - -### Contoh: tanpa akses sistem file/shell (messaging provider diizinkan) - -```json5 -{ - agents: { - list: [ - { - id: "public", - workspace: "~/.openclaw/workspace-public", - sandbox: { - mode: "all", - scope: "agent", - workspaceAccess: "none", - }, - // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools - // to the current session + spawned subagent sessions, but you can clamp further if needed. - // See `tools.sessions.visibility` in the configuration reference. - tools: { - sessions: { visibility: "tree" }, // self | tree | agent | all - allow: [ - "sessions_list", - "sessions_history", - "sessions_send", - "sessions_spawn", - "session_status", - "whatsapp", - "telegram", - "slack", - "discord", - ], - deny: [ - "read", - "write", - "edit", - "apply_patch", - "exec", - "process", - "browser", - "canvas", - "nodes", - "cron", - "gateway", - "image", - ], - }, - }, - ], - }, -} -``` - +__OC_I18N_900018__ +### Contoh: tool baca saja + workspace baca saja +__OC_I18N_900019__ +### Contoh: tanpa akses filesystem/shell (pesan provider diizinkan) +__OC_I18N_900020__ ## Respons insiden Jika AI Anda melakukan sesuatu yang buruk: -### Tahan +### Contain -1. **Hentikan:** hentikan aplikasi macOS (jika aplikasi mengawasi Gateway) atau akhiri proses `openclaw gateway` Anda. -2. **Tutup paparan:** setel `gateway.bind: "loopback"` (atau nonaktifkan Tailscale Funnel/Serve) sampai Anda memahami apa yang terjadi. +1. **Hentikan:** hentikan aplikasi macOS (jika aplikasi itu mengawasi Gateway) atau hentikan proses `openclaw gateway` Anda. +2. **Tutup eksposur:** setel `gateway.bind: "loopback"` (atau nonaktifkan Tailscale Funnel/Serve) sampai Anda memahami apa yang terjadi. 3. **Bekukan akses:** alihkan DM/grup berisiko ke `dmPolicy: "disabled"` / wajibkan mention, dan hapus entri allow-all `"*"` jika Anda memilikinya. -### Rotasi (anggap kompromi jika secret bocor) +### Rotasi (anggap kompromi jika rahasia bocor) -1. Rotasi auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) dan restart. -2. Rotasi secret klien jarak jauh (`gateway.remote.token` / `.password`) pada mesin mana pun yang dapat memanggil Gateway. -3. Rotasi kredensial provider/API (kredensial WhatsApp, token Slack/Discord, kunci model/API di `auth-profiles.json`, dan nilai payload secret terenkripsi saat digunakan). +1. Rotasi auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) dan mulai ulang. +2. Rotasi rahasia klien remote (`gateway.remote.token` / `.password`) pada mesin apa pun yang dapat memanggil Gateway. +3. Rotasi kredensial provider/API (kredensial WhatsApp, token Slack/Discord, kunci model/API di `auth-profiles.json`, dan nilai payload rahasia terenkripsi saat digunakan). ### Audit 1. Periksa log Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (atau `logging.file`). 2. Tinjau transkrip yang relevan: `~/.openclaw/agents//sessions/*.jsonl`. 3. Tinjau perubahan konfigurasi terbaru (apa pun yang dapat memperluas akses: `gateway.bind`, `gateway.auth`, kebijakan DM/grup, `tools.elevated`, perubahan plugin). -4. Jalankan ulang `openclaw security audit --deep` dan pastikan temuan kritis sudah diselesaikan. +4. Jalankan ulang `openclaw security audit --deep` dan konfirmasi temuan kritis telah diselesaikan. ### Kumpulkan untuk laporan - Timestamp, OS host gateway + versi OpenClaw -- Transkrip sesi + tail log pendek (setelah redaksi) -- Apa yang dikirim penyerang + apa yang dilakukan agen -- Apakah Gateway terekspos melampaui loopback (LAN/Tailscale Funnel/Serve) +- Transkrip sesi + tail log singkat (setelah disunting) +- Apa yang dikirim penyerang + apa yang dilakukan agent +- Apakah Gateway terekspos di luar loopback (LAN/Tailscale Funnel/Serve) -## Pemindaian secret dengan detect-secrets +## Pemindaian rahasia dengan detect-secrets CI menjalankan hook pre-commit `detect-secrets` dalam job `secrets`. -Push ke `main` selalu menjalankan pemindaian semua file. Pull request menggunakan jalur cepat changed-file -ketika commit dasar tersedia, dan fallback ke pemindaian semua file +Push ke `main` selalu menjalankan pemindaian semua file. Pull request menggunakan jalur cepat +file yang berubah saat commit dasar tersedia, dan fallback ke pemindaian semua file jika tidak. Jika gagal, ada kandidat baru yang belum ada di baseline. ### Jika CI gagal 1. Reproduksi secara lokal: - - ```bash - pre-commit run --all-files detect-secrets - ``` - +__OC_I18N_900021__ 2. Pahami tool: - - `detect-secrets` di pre-commit menjalankan `detect-secrets-hook` dengan + - `detect-secrets` dalam pre-commit menjalankan `detect-secrets-hook` dengan baseline dan exclude repo. - `detect-secrets audit` membuka tinjauan interaktif untuk menandai setiap item baseline sebagai nyata atau false positive. -3. Untuk secret nyata: rotasi/hapus secret tersebut, lalu jalankan ulang pemindaian untuk memperbarui baseline. +3. Untuk rahasia nyata: rotasi/hapus, lalu jalankan ulang pemindaian untuk memperbarui baseline. 4. Untuk false positive: jalankan audit interaktif dan tandai sebagai false: - - ```bash - detect-secrets audit .secrets.baseline - ``` - +__OC_I18N_900022__ 5. Jika Anda membutuhkan exclude baru, tambahkan ke `.detect-secrets.cfg` dan regenerasi baseline dengan flag `--exclude-files` / `--exclude-lines` yang cocok (file config hanya referensi; detect-secrets tidak membacanya secara otomatis). @@ -1334,6 +1123,6 @@ Commit `.secrets.baseline` yang diperbarui setelah mencerminkan state yang dimak Menemukan kerentanan di OpenClaw? Harap laporkan secara bertanggung jawab: -1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Jangan posting secara publik sampai diperbaiki -3. Kami akan memberi kredit kepada Anda (kecuali Anda memilih anonim) +1. Surel: [security@openclaw.ai](mailto:security@openclaw.ai) +2. Jangan publikasikan secara umum hingga diperbaiki +3. Kami akan mencantumkan kredit untuk Anda (kecuali Anda lebih memilih anonim) diff --git a/docs/id/plugins/codex-harness.md b/docs/id/plugins/codex-harness.md index ca472643d..a612a05a7 100644 --- a/docs/id/plugins/codex-harness.md +++ b/docs/id/plugins/codex-harness.md @@ -2,121 +2,122 @@ read_when: - Anda ingin menggunakan harness app-server Codex yang disertakan - Anda memerlukan contoh konfigurasi harness Codex - - Anda ingin penerapan khusus Codex gagal alih-alih kembali ke PI -summary: Jalankan giliran agen tertanam OpenClaw melalui kerangka app-server Codex bawaan + - Anda ingin penerapan khusus Codex gagal alih-alih beralih ke PI sebagai cadangan +summary: Jalankan giliran agen tertanam OpenClaw melalui harness app-server Codex yang disertakan title: Kerangka kerja Codex x-i18n: - generated_at: "2026-04-30T10:00:38Z" + generated_at: "2026-04-30T20:05:51Z" model: gpt-5.5 provider: openai - source_hash: 93abb72e9590aad265e5b6b8691dd16314178c4d255679b4e53da33b792a6e6b + source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f source_path: plugins/codex-harness.md workflow: 16 --- Plugin `codex` bawaan memungkinkan OpenClaw menjalankan giliran agen tertanam melalui -app-server Codex, bukan harness PI bawaan. +app-server Codex alih-alih harness PI bawaan. -Gunakan ini saat Anda ingin Codex memiliki sesi agen tingkat rendah: penemuan -model, melanjutkan thread native, compaction native, dan eksekusi app-server. -OpenClaw tetap memiliki channel chat, file sesi, pemilihan model, tools, -persetujuan, pengiriman media, dan mirror transkrip yang terlihat. +Gunakan ini ketika Anda ingin Codex menangani sesi agen tingkat rendah: penemuan +model, pelanjutan thread native, compaction native, dan eksekusi app-server. +OpenClaw tetap menangani saluran chat, file sesi, pemilihan model, alat, +persetujuan, pengiriman media, dan cermin transkrip yang terlihat. -Jika Anda mencoba mencari orientasi, mulai dengan +Jika Anda mencoba memahami arahnya, mulai dari [Runtime agen](/id/concepts/agent-runtimes). Versi singkatnya adalah: `openai/gpt-5.5` adalah ref model, `codex` adalah runtime, dan Telegram, -Discord, Slack, atau channel lain tetap menjadi permukaan komunikasi. +Discord, Slack, atau saluran lain tetap menjadi permukaan komunikasi. ## Yang diubah Plugin ini -Plugin `codex` bawaan menyumbang beberapa kapabilitas terpisah: +Plugin `codex` bawaan menyediakan beberapa kemampuan terpisah: -| Kapabilitas | Cara menggunakannya | Yang dilakukannya | -| -------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- | -| Runtime tertanam native | `agentRuntime.id: "codex"` | Menjalankan giliran agen tertanam OpenClaw melalui app-server Codex. | -| Perintah kontrol chat native | `/codex bind`, `/codex resume`, `/codex steer`, ... | Mengikat dan mengontrol thread app-server Codex dari percakapan pesan. | -| Penyedia/katalog app-server Codex | internal `codex`, ditampilkan melalui harness | Memungkinkan runtime menemukan dan memvalidasi model app-server. | -| Jalur pemahaman media Codex | jalur kompatibilitas model gambar `codex/*` | Menjalankan giliran app-server Codex terbatas untuk model pemahaman gambar yang didukung. | -| Relay hook native | Hook Plugin di sekitar event native Codex | Memungkinkan OpenClaw mengamati/memblokir event tool/finalisasi native Codex yang didukung. | +| Kemampuan | Cara menggunakannya | Fungsinya | +| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Runtime tertanam native | `agentRuntime.id: "codex"` | Menjalankan giliran agen tertanam OpenClaw melalui app-server Codex. | +| Perintah kontrol chat native | `/codex bind`, `/codex resume`, `/codex steer`, ... | Mengikat dan mengontrol thread app-server Codex dari percakapan pesan. | +| Penyedia/katalog app-server Codex | internal `codex`, diekspos melalui harness | Memungkinkan runtime menemukan dan memvalidasi model app-server. | +| Jalur pemahaman media Codex | jalur kompatibilitas model gambar `codex/*` | Menjalankan giliran app-server Codex terbatas untuk model pemahaman gambar yang didukung. | +| Relay hook native | Hook Plugin di sekitar event Codex-native | Memungkinkan OpenClaw mengamati/memblokir event alat/finalisasi Codex-native yang didukung. | -Mengaktifkan Plugin membuat kapabilitas tersebut tersedia. Ini **tidak**: +Mengaktifkan Plugin membuat kemampuan tersebut tersedia. Ini **tidak**: - mulai menggunakan Codex untuk setiap model OpenAI - mengonversi ref model `openai-codex/*` menjadi runtime native - menjadikan ACP/acpx jalur Codex default -- melakukan hot-switch sesi yang sudah merekam runtime PI -- menggantikan pengiriman channel OpenClaw, file sesi, penyimpanan profil auth, atau - routing pesan +- melakukan hot-switch pada sesi yang sudah merekam runtime PI +- mengganti pengiriman saluran OpenClaw, file sesi, penyimpanan profil auth, atau + perutean pesan -Plugin yang sama juga memiliki permukaan perintah kontrol chat native `/codex`. Jika +Plugin yang sama juga menangani permukaan perintah kontrol chat `/codex` native. Jika Plugin diaktifkan dan pengguna meminta untuk mengikat, melanjutkan, mengarahkan, menghentikan, atau memeriksa -thread Codex dari chat, agen sebaiknya memilih `/codex ...` dibanding ACP. ACP tetap -menjadi fallback eksplisit saat pengguna meminta ACP/acpx atau sedang menguji adapter ACP +thread Codex dari chat, agen sebaiknya memilih `/codex ...` daripada ACP. ACP tetap +menjadi fallback eksplisit ketika pengguna meminta ACP/acpx atau sedang menguji adapter ACP Codex. -Giliran native Codex menjaga hook Plugin OpenClaw sebagai lapisan kompatibilitas publik. +Giliran Codex native mempertahankan hook Plugin OpenClaw sebagai lapisan kompatibilitas publik. Ini adalah hook OpenClaw dalam proses, bukan hook perintah `hooks.json` Codex: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` untuk catatan transkrip mirror +- `before_message_write` untuk catatan transkrip yang dicerminkan - `before_agent_finalize` melalui relay `Stop` Codex - `agent_end` -Plugin juga dapat mendaftarkan middleware hasil tool yang netral runtime untuk menulis ulang -hasil tool dinamis OpenClaw setelah OpenClaw mengeksekusi tool dan sebelum +Plugin juga dapat mendaftarkan middleware hasil alat yang netral-runtime untuk menulis ulang +hasil alat dinamis OpenClaw setelah OpenClaw mengeksekusi alat dan sebelum hasil dikembalikan ke Codex. Ini terpisah dari hook Plugin publik -`tool_result_persist`, yang mentransformasi penulisan hasil tool transkrip milik OpenClaw. +`tool_result_persist`, yang mentransformasi penulisan hasil alat transkrip +milik OpenClaw. Untuk semantik hook Plugin itu sendiri, lihat [Hook Plugin](/id/plugins/hooks) -dan [Perilaku penjaga Plugin](/id/tools/plugin). +dan [Perilaku guard Plugin](/id/tools/plugin). -Harness nonaktif secara default. Config baru sebaiknya menjaga ref model OpenAI -kanonis sebagai `openai/gpt-*` dan secara eksplisit memaksa -`agentRuntime.id: "codex"` atau `OPENCLAW_AGENT_RUNTIME=codex` saat mereka -menginginkan eksekusi app-server native. Ref model legacy `codex/*` tetap otomatis memilih -harness untuk kompatibilitas, tetapi prefix penyedia legacy yang didukung runtime +Harness nonaktif secara default. Konfigurasi baru sebaiknya menjaga ref model OpenAI +tetap kanonis sebagai `openai/gpt-*` dan secara eksplisit memaksa +`agentRuntime.id: "codex"` atau `OPENCLAW_AGENT_RUNTIME=codex` ketika ingin +eksekusi app-server native. Ref model legacy `codex/*` masih memilih otomatis +harness untuk kompatibilitas, tetapi prefiks penyedia legacy yang didukung runtime tidak ditampilkan sebagai pilihan model/penyedia normal. Jika Plugin `codex` diaktifkan tetapi model utama masih -`openai-codex/*`, `openclaw doctor` memberi peringatan alih-alih mengubah route. Itu +`openai-codex/*`, `openclaw doctor` memberi peringatan alih-alih mengubah rute. Itu disengaja: `openai-codex/*` tetap menjadi jalur OAuth/langganan PI Codex, dan eksekusi app-server native tetap menjadi pilihan runtime eksplisit. -## Peta route +## Peta rute -Gunakan tabel ini sebelum mengubah config: +Gunakan tabel ini sebelum mengubah konfigurasi: -| Perilaku yang diinginkan | Ref model | Config runtime | Persyaratan Plugin | Label status yang diharapkan | -| ----------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | -| API OpenAI melalui runner OpenClaw normal | `openai/gpt-*` | dihilangkan atau `runtime: "pi"` | Penyedia OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/langganan Codex melalui PI | `openai-codex/gpt-*` | dihilangkan atau `runtime: "pi"` | Penyedia OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| Giliran tertanam app-server native Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Penyedia campuran dengan mode auto konservatif | ref spesifik penyedia | `agentRuntime.id: "auto"` | Runtime Plugin opsional | Bergantung pada runtime terpilih | -| Sesi adapter ACP Codex eksplisit | bergantung prompt/model ACP | `sessions_spawn` dengan `runtime: "acp"` | backend `acpx` sehat | Status tugas/sesi ACP | +| Perilaku yang diinginkan | Ref model | Konfigurasi runtime | Kebutuhan Plugin | Label status yang diharapkan | +| ---------------------------------------- | -------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ | +| API OpenAI melalui runner OpenClaw normal | `openai/gpt-*` | dihilangkan atau `runtime: "pi"` | Penyedia OpenAI | `Runtime: OpenClaw Pi Default` | +| OAuth/langganan Codex melalui PI | `openai-codex/gpt-*` | dihilangkan atau `runtime: "pi"` | Penyedia OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | +| Giliran tertanam app-server Codex native | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | +| Penyedia campuran dengan mode otomatis konservatif | ref khusus penyedia | `agentRuntime.id: "auto"` | Runtime Plugin opsional | Bergantung pada runtime yang dipilih | +| Sesi adapter ACP Codex eksplisit | bergantung pada prompt/model ACP | `sessions_spawn` dengan `runtime: "acp"` | backend `acpx` sehat | Status tugas/sesi ACP | -Pembagian pentingnya adalah penyedia versus runtime: +Pemisahan pentingnya adalah penyedia versus runtime: -- `openai-codex/*` menjawab "route penyedia/auth mana yang harus PI gunakan?" +- `openai-codex/*` menjawab "rute penyedia/auth mana yang harus digunakan PI?" - `agentRuntime.id: "codex"` menjawab "loop mana yang harus mengeksekusi giliran tertanam ini?" -- `/codex ...` menjawab "percakapan native Codex mana yang harus diikat +- `/codex ...` menjawab "percakapan Codex native mana yang harus diikat atau dikontrol chat ini?" - ACP menjawab "proses harness eksternal mana yang harus diluncurkan acpx?" -## Pilih prefix model yang tepat +## Pilih prefiks model yang tepat -Route keluarga OpenAI bersifat spesifik prefix. Gunakan `openai-codex/*` saat Anda ingin -OAuth Codex melalui PI; gunakan `openai/*` saat Anda ingin akses API OpenAI langsung atau -saat Anda memaksa harness app-server native Codex: +Rute keluarga OpenAI bersifat spesifik prefiks. Gunakan `openai-codex/*` ketika Anda menginginkan +OAuth Codex melalui PI; gunakan `openai/*` ketika Anda menginginkan akses API OpenAI langsung atau +ketika Anda memaksa harness app-server Codex native: -| Ref model | Jalur runtime | Gunakan saat | -| --------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Penyedia OpenAI melalui plumbing OpenClaw/PI | Anda ingin akses API OpenAI Platform langsung saat ini dengan `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex melalui OpenClaw/PI | Anda ingin auth langganan ChatGPT/Codex dengan runner PI default. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness app-server Codex | Anda ingin eksekusi app-server native Codex untuk giliran agen tertanam. | +| Ref model | Jalur runtime | Gunakan ketika | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Penyedia OpenAI melalui plumbing OpenClaw/PI | Anda menginginkan akses API OpenAI Platform langsung saat ini dengan `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OAuth OpenAI Codex melalui OpenClaw/PI | Anda menginginkan auth langganan ChatGPT/Codex dengan runner PI default. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness app-server Codex | Anda menginginkan eksekusi app-server Codex native untuk giliran agen tertanam. | GPT-5.5 saat ini hanya langganan/OAuth di OpenClaw. Gunakan `openai-codex/gpt-5.5` untuk OAuth PI, atau `openai/gpt-5.5` dengan harness @@ -125,55 +126,55 @@ setelah OpenAI mengaktifkan GPT-5.5 di API publik. Ref legacy `codex/gpt-*` tetap diterima sebagai alias kompatibilitas. Migrasi kompatibilitas doctor menulis ulang ref runtime utama legacy menjadi ref model -kanonis dan mencatat kebijakan runtime secara terpisah, sedangkan ref legacy yang hanya fallback -dibiarkan tidak berubah karena runtime dikonfigurasi untuk seluruh container agen. -Config OAuth PI Codex baru sebaiknya menggunakan `openai-codex/gpt-*`; config harness -app-server native baru sebaiknya menggunakan `openai/gpt-*` plus +kanonis dan merekam kebijakan runtime secara terpisah, sementara ref legacy yang hanya fallback +dibiarkan tidak berubah karena runtime dikonfigurasi untuk seluruh kontainer agen. +Konfigurasi OAuth PI Codex baru sebaiknya menggunakan `openai-codex/gpt-*`; konfigurasi +harness app-server native baru sebaiknya menggunakan `openai/gpt-*` plus `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` mengikuti pembagian prefix yang sama. Gunakan -`openai-codex/gpt-*` saat pemahaman gambar harus berjalan melalui jalur penyedia OAuth -OpenAI Codex. Gunakan `codex/gpt-*` saat pemahaman gambar harus berjalan +`agents.defaults.imageModel` mengikuti pemisahan prefiks yang sama. Gunakan +`openai-codex/gpt-*` ketika pemahaman gambar harus berjalan melalui jalur penyedia OAuth OpenAI +Codex. Gunakan `codex/gpt-*` ketika pemahaman gambar harus berjalan melalui giliran app-server Codex terbatas. Model app-server Codex harus -mengiklankan dukungan input gambar; model Codex khusus teks gagal sebelum giliran media +mengiklankan dukungan input gambar; model Codex yang hanya teks gagal sebelum giliran media dimulai. Gunakan `/status` untuk mengonfirmasi harness efektif untuk sesi saat ini. Jika pilihannya mengejutkan, aktifkan logging debug untuk subsistem `agents/harness` -dan periksa catatan terstruktur `agent harness selected` milik gateway. Catatan itu -mencakup id harness terpilih, alasan pemilihan, kebijakan runtime/fallback, dan, +dan periksa catatan terstruktur gateway `agent harness selected`. Catatan itu +menyertakan id harness yang dipilih, alasan pemilihan, kebijakan runtime/fallback, dan, dalam mode `auto`, hasil dukungan setiap kandidat Plugin. ### Arti peringatan doctor -`openclaw doctor` memberi peringatan saat semua hal ini benar: +`openclaw doctor` memberi peringatan ketika semua ini benar: - Plugin `codex` bawaan diaktifkan atau diizinkan - model utama agen adalah `openai-codex/*` - runtime efektif agen tersebut bukan `codex` Peringatan itu ada karena pengguna sering mengharapkan "Plugin Codex diaktifkan" berarti -"runtime app-server native Codex." OpenClaw tidak melakukan lompatan itu. Peringatan +"runtime app-server Codex native." OpenClaw tidak membuat lompatan itu. Peringatan berarti: -- **Tidak perlu perubahan** jika Anda memang menginginkan OAuth ChatGPT/Codex melalui PI. -- Ubah model menjadi `openai/` dan setel - `agentRuntime.id: "codex"` jika Anda menginginkan eksekusi +- **Tidak ada perubahan yang diperlukan** jika Anda memang bermaksud menggunakan OAuth ChatGPT/Codex melalui PI. +- Ubah model ke `openai/` dan atur + `agentRuntime.id: "codex"` jika Anda bermaksud menggunakan eksekusi app-server native. - Sesi yang ada tetap memerlukan `/new` atau `/reset` setelah perubahan runtime, - karena pin runtime sesi bersifat melekat. + karena pin runtime sesi bersifat lekat. Pemilihan harness bukan kontrol sesi langsung. Saat giliran tertanam berjalan, -OpenClaw mencatat id harness terpilih pada sesi tersebut dan terus menggunakannya untuk -giliran berikutnya dalam id sesi yang sama. Ubah config `agentRuntime` atau -`OPENCLAW_AGENT_RUNTIME` saat Anda ingin sesi mendatang menggunakan harness lain; -gunakan `/new` atau `/reset` untuk memulai sesi baru sebelum mengalihkan percakapan yang ada -antara PI dan Codex. Ini menghindari memutar ulang satu transkrip melalui +OpenClaw merekam id harness yang dipilih pada sesi tersebut dan terus menggunakannya untuk +giliran berikutnya dalam id sesi yang sama. Ubah konfigurasi `agentRuntime` atau +`OPENCLAW_AGENT_RUNTIME` ketika Anda ingin sesi mendatang menggunakan harness lain; +gunakan `/new` atau `/reset` untuk memulai sesi baru sebelum mengganti percakapan yang ada +antara PI dan Codex. Ini menghindari pemutaran ulang satu transkrip melalui dua sistem sesi native yang tidak kompatibel. -Sesi legacy yang dibuat sebelum pin harness diperlakukan sebagai ter-pin PI setelah mereka +Sesi legacy yang dibuat sebelum pin harness diperlakukan sebagai terpin PI setelah memiliki riwayat transkrip. Gunakan `/new` atau `/reset` untuk memasukkan percakapan itu ke -Codex setelah mengubah config. +Codex setelah mengubah konfigurasi. `/status` menampilkan runtime model efektif. Harness PI default muncul sebagai `Runtime: OpenClaw Pi Default`, dan harness app-server Codex muncul sebagai @@ -182,20 +183,23 @@ Codex setelah mengubah config. ## Persyaratan - OpenClaw dengan Plugin `codex` bawaan tersedia. -- App-server Codex `0.125.0` atau lebih baru. Plugin bawaan mengelola binary +- app-server Codex `0.125.0` atau lebih baru. Plugin bawaan mengelola biner app-server Codex yang kompatibel secara default, sehingga perintah `codex` lokal di `PATH` tidak memengaruhi startup harness normal. -- Auth Codex tersedia untuk proses app-server atau untuk bridge auth Codex - OpenClaw. +- Auth Codex tersedia untuk proses app-server atau untuk jembatan auth Codex + OpenClaw. Peluncuran app-server stdio lokal menggunakan home Codex yang dikelola OpenClaw untuk setiap + agen dan child `HOME` terisolasi, sehingga secara default tidak membaca akun + `~/.codex`, Skills, plugin, konfigurasi, status thread, atau + `$HOME/.agents/skills` native pribadi Anda. Plugin memblokir handshake app-server yang lebih lama atau tidak berversi. Itu menjaga -OpenClaw pada permukaan protokol yang telah diuji. +OpenClaw tetap pada permukaan protokol yang telah diuji. Untuk pengujian smoke live dan Docker, auth biasanya berasal dari akun CLI Codex atau profil auth `openai-codex` OpenClaw. Peluncuran app-server stdio lokal juga dapat -fallback ke `CODEX_API_KEY` / `OPENAI_API_KEY` saat tidak ada akun. +fallback ke `CODEX_API_KEY` / `OPENAI_API_KEY` ketika tidak ada akun. -## Config minimal +## Konfigurasi minimal Gunakan `openai/gpt-5.5`, aktifkan Plugin bawaan, dan paksa harness `codex`: @@ -219,7 +223,7 @@ Gunakan `openai/gpt-5.5`, aktifkan Plugin bawaan, dan paksa harness `codex`: } ``` -Jika config Anda menggunakan `plugins.allow`, sertakan juga `codex` di sana: +Jika konfigurasi Anda menggunakan `plugins.allow`, sertakan `codex` di sana juga: ```json5 { @@ -234,24 +238,24 @@ Jika config Anda menggunakan `plugins.allow`, sertakan juga `codex` di sana: } ``` -Config legacy yang menyetel `agents.defaults.model` atau model agen menjadi -`codex/` tetap otomatis mengaktifkan Plugin `codex` bawaan. Config baru sebaiknya -memilih `openai/` plus entri eksplisit `agentRuntime` di atas. +Konfigurasi legacy yang mengatur `agents.defaults.model` atau model agen ke +`codex/` tetap otomatis mengaktifkan Plugin `codex` bawaan. Konfigurasi baru sebaiknya +memilih `openai/` plus entri `agentRuntime` eksplisit di atas. ## Tambahkan Codex bersama model lain -Jangan setel `agentRuntime.id: "codex"` secara global jika agen yang sama harus bebas beralih -antara Codex dan model penyedia non-Codex. Runtime paksa berlaku untuk setiap -giliran tertanam untuk agen atau sesi tersebut. Jika Anda memilih model Anthropic saat -runtime itu dipaksa, OpenClaw tetap mencoba harness Codex dan gagal tertutup -alih-alih diam-diam me-route giliran itu melalui PI. +Jangan tetapkan `agentRuntime.id: "codex"` secara global jika agen yang sama harus bebas beralih +antara Codex dan model penyedia non-Codex. Runtime yang dipaksakan berlaku untuk setiap +giliran tertanam bagi agen atau sesi tersebut. Jika Anda memilih model Anthropic saat +runtime itu dipaksakan, OpenClaw tetap mencoba harness Codex dan gagal tertutup +alih-alih diam-diam merutekan giliran itu melalui PI. Gunakan salah satu bentuk ini sebagai gantinya: -- Letakkan Codex pada agen khusus dengan `agentRuntime.id: "codex"`. +- Tempatkan Codex pada agen khusus dengan `agentRuntime.id: "codex"`. - Pertahankan agen default pada `agentRuntime.id: "auto"` dan fallback PI untuk penggunaan penyedia campuran normal. -- Gunakan ref `codex/*` lama hanya untuk kompatibilitas. Konfigurasi baru sebaiknya memilih +- Gunakan referensi legacy `codex/*` hanya untuk kompatibilitas. Konfigurasi baru sebaiknya memilih `openai/*` plus kebijakan runtime Codex yang eksplisit. Misalnya, ini mempertahankan agen default pada pemilihan otomatis normal dan @@ -296,34 +300,34 @@ Dengan bentuk ini: - Agen default `main` menggunakan jalur penyedia normal dan fallback kompatibilitas PI. - Agen `codex` menggunakan harness app-server Codex. -- Jika Codex hilang atau tidak didukung untuk agen `codex`, giliran akan gagal +- Jika Codex tidak ada atau tidak didukung untuk agen `codex`, giliran akan gagal alih-alih diam-diam menggunakan PI. ## Perutean perintah agen -Agen harus merutekan permintaan pengguna berdasarkan niat, bukan hanya berdasarkan kata "Codex": +Agen harus merutekan permintaan pengguna berdasarkan niat, bukan berdasarkan kata "Codex" saja: -| Pengguna meminta... | Agen sebaiknya menggunakan... | +| Pengguna meminta... | Agen harus menggunakan... | | -------------------------------------------------------- | ------------------------------------------------ | | "Ikat chat ini ke Codex" | `/codex bind` | -| "Lanjutkan thread Codex `` di sini" | `/codex resume ` | -| "Tampilkan thread Codex" | `/codex threads` | -| "Ajukan laporan dukungan untuk proses Codex yang buruk" | `/diagnostics [note]` | -| "Hanya kirim umpan balik Codex untuk thread terlampir ini" | `/codex diagnostics [note]` | +| "Lanjutkan utas Codex `` di sini" | `/codex resume ` | +| "Tampilkan utas Codex" | `/codex threads` | +| "Buat laporan dukungan untuk eksekusi Codex yang buruk" | `/diagnostics [note]` | +| "Kirim feedback Codex hanya untuk utas terlampir ini" | `/codex diagnostics [note]` | | "Gunakan Codex sebagai runtime untuk agen ini" | perubahan konfigurasi ke `agentRuntime.id` | -| "Gunakan langganan ChatGPT/Codex saya dengan OpenClaw normal" | ref model `openai-codex/*` | +| "Gunakan langganan ChatGPT/Codex saya dengan OpenClaw normal" | referensi model `openai-codex/*` | | "Jalankan Codex melalui ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Mulai Claude Code/Gemini/OpenCode/Cursor dalam sebuah thread" | ACP/acpx, bukan `/codex` dan bukan sub-agen native | +| "Mulai Claude Code/Gemini/OpenCode/Cursor dalam utas" | ACP/acpx, bukan `/codex` dan bukan sub-agen native | OpenClaw hanya mengiklankan panduan spawn ACP kepada agen saat ACP diaktifkan, dapat didispatch, dan didukung oleh backend runtime yang dimuat. Jika ACP tidak tersedia, -prompt sistem dan Skills plugin tidak boleh mengajarkan agen tentang perutean ACP. +prompt sistem dan Skills plugin tidak boleh mengajari agen tentang perutean ACP. ## Deployment khusus Codex Paksa harness Codex saat Anda perlu membuktikan bahwa setiap giliran agen tertanam -menggunakan Codex. Runtime Plugin eksplisit default tanpa fallback PI, jadi -`fallback: "none"` bersifat opsional tetapi sering berguna sebagai dokumentasi: +menggunakan Codex. Runtime plugin eksplisit default-nya tanpa fallback PI, jadi +`fallback: "none"` opsional tetapi sering berguna sebagai dokumentasi: ```json5 { @@ -345,14 +349,14 @@ Override lingkungan: OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Dengan Codex dipaksa, OpenClaw gagal lebih awal jika plugin Codex dinonaktifkan, +Dengan Codex dipaksakan, OpenClaw gagal lebih awal jika plugin Codex dinonaktifkan, app-server terlalu lama, atau app-server tidak dapat dimulai. Tetapkan `OPENCLAW_AGENT_HARNESS_FALLBACK=pi` hanya jika Anda sengaja ingin PI menangani -pemilihan harness yang hilang. +pemilihan harness yang tidak ada. ## Codex per agen -Anda dapat membuat satu agen hanya-Codex sementara agen default tetap memakai +Anda dapat membuat satu agen khusus Codex sementara agen default tetap memakai pemilihan otomatis normal: ```json5 @@ -385,20 +389,20 @@ pemilihan otomatis normal: ``` Gunakan perintah sesi normal untuk beralih agen dan model. `/new` membuat sesi -OpenClaw baru dan harness Codex membuat atau melanjutkan thread app-server sidecar -sesuai kebutuhan. `/reset` menghapus binding sesi OpenClaw untuk thread tersebut -dan membiarkan giliran berikutnya menyelesaikan harness dari konfigurasi saat ini lagi. +OpenClaw baru dan harness Codex membuat atau melanjutkan utas app-server sidecar-nya +sesuai kebutuhan. `/reset` menghapus binding sesi OpenClaw untuk utas tersebut +dan memungkinkan giliran berikutnya menyelesaikan harness dari konfigurasi saat ini lagi. ## Penemuan model -Secara default, plugin Codex meminta model yang tersedia kepada app-server. Jika -penemuan gagal atau timeout, plugin menggunakan katalog fallback bawaan untuk: +Secara default, plugin Codex meminta app-server untuk model yang tersedia. Jika +penemuan gagal atau timeout, ia menggunakan katalog fallback bawaan untuk: - GPT-5.5 - GPT-5.4 mini - GPT-5.2 -Anda dapat menyetel penemuan di bawah `plugins.entries.codex.config.discovery`: +Anda dapat menyesuaikan penemuan di bawah `plugins.entries.codex.config.discovery`: ```json5 { @@ -440,21 +444,22 @@ katalog fallback: ## Koneksi dan kebijakan app-server -Secara default, plugin memulai binary Codex terkelola OpenClaw secara lokal dengan: +Secara default, plugin memulai binary Codex terkelola milik OpenClaw secara lokal dengan: ```bash codex app-server --listen stdio:// ``` Binary terkelola dideklarasikan sebagai dependensi runtime plugin bawaan dan di-stage -bersama dependensi plugin `codex` lainnya. Ini menjaga versi app-server tetap terikat -ke plugin bawaan, bukan ke CLI Codex terpisah mana pun yang kebetulan terinstal lokal. -Tetapkan `appServer.command` hanya saat Anda sengaja ingin menjalankan executable berbeda. +bersama dependensi plugin `codex` lainnya. Ini membuat versi app-server +terikat ke plugin bawaan, bukan ke CLI Codex terpisah mana pun yang kebetulan +terpasang secara lokal. Tetapkan `appServer.command` hanya saat Anda +sengaja ingin menjalankan executable yang berbeda. Secara default, OpenClaw memulai sesi harness Codex lokal dalam mode YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"`, dan `sandbox: "danger-full-access"`. Ini adalah postur operator lokal tepercaya yang digunakan -untuk Heartbeat otonom: Codex dapat menggunakan tool shell dan jaringan tanpa +untuk Heartbeat otonom: Codex dapat menggunakan shell dan alat jaringan tanpa berhenti pada prompt persetujuan native yang tidak ada orang untuk menjawabnya. Untuk ikut menggunakan persetujuan yang ditinjau guardian Codex, tetapkan `appServer.mode: @@ -478,16 +483,16 @@ Untuk ikut menggunakan persetujuan yang ditinjau guardian Codex, tetapkan `appSe } ``` -Mode Guardian menggunakan jalur persetujuan auto-review native Codex. Saat Codex meminta untuk +Mode Guardian menggunakan jalur persetujuan auto-review native Codex. Saat Codex meminta keluar dari sandbox, menulis di luar workspace, atau menambahkan izin seperti akses jaringan, -Codex merutekan permintaan persetujuan tersebut ke peninjau native, bukan prompt manusia. -Peninjau menerapkan kerangka risiko Codex dan menyetujui atau menolak permintaan spesifik tersebut. -Gunakan Guardian saat Anda menginginkan guardrail lebih banyak daripada mode YOLO +Codex merutekan permintaan persetujuan itu ke peninjau native alih-alih prompt +manusia. Peninjau menerapkan kerangka risiko Codex dan menyetujui atau menolak +permintaan spesifik tersebut. Gunakan Guardian saat Anda menginginkan guardrail lebih banyak daripada mode YOLO tetapi tetap membutuhkan agen tanpa pengawasan untuk terus berjalan. Preset `guardian` diperluas menjadi `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"`, dan `sandbox: "workspace-write"`. -Field kebijakan individual tetap mengesampingkan `mode`, sehingga deployment lanjutan dapat mencampur +Field kebijakan individual tetap mengoverride `mode`, sehingga deployment tingkat lanjut dapat mencampur preset dengan pilihan eksplisit. Nilai peninjau lama `guardian_subagent` masih diterima sebagai alias kompatibilitas, tetapi konfigurasi baru sebaiknya menggunakan `auto_review`. @@ -515,24 +520,47 @@ Untuk app-server yang sudah berjalan, gunakan transport WebSocket: ``` Peluncuran app-server stdio mewarisi lingkungan proses OpenClaw secara default, -tetapi OpenClaw memiliki bridge akun app-server Codex. Auth dipilih dalam urutan ini: +tetapi OpenClaw memiliki bridge akun app-server Codex dan menetapkan baik +`CODEX_HOME` maupun `HOME` ke direktori per agen di bawah state OpenClaw agen tersebut. +Loader skill milik Codex membaca `$CODEX_HOME/skills` dan +`$HOME/.agents/skills`, sehingga kedua nilai diisolasi untuk peluncuran app-server +lokal. Itu menjaga skill native Codex, plugin, konfigurasi, akun, dan state utas +tetap tercakup ke agen OpenClaw alih-alih bocor dari home CLI Codex pribadi +operator. -1. Profil auth Codex OpenClaw eksplisit untuk agen. -2. Akun app-server yang sudah ada, seperti sign-in ChatGPT CLI Codex lokal. +Plugin OpenClaw dan snapshot skill OpenClaw tetap mengalir melalui registry plugin +dan loader skill milik OpenClaw. Aset CLI Codex pribadi tidak. Jika Anda memiliki +skill atau plugin CLI Codex berguna yang harus menjadi bagian dari agen OpenClaw, +inventarisasikan secara eksplisit: + +```bash +openclaw migrate codex --dry-run +openclaw migrate apply codex --yes +``` + +Penyedia migrasi Codex menyalin skill ke workspace agen OpenClaw saat ini. +Plugin native Codex, hook, dan file konfigurasi dilaporkan atau diarsipkan +untuk peninjauan manual alih-alih diaktifkan otomatis, karena mereka dapat +mengeksekusi perintah, mengekspos server MCP, atau membawa kredensial. + +Auth dipilih dalam urutan ini: + +1. Profil auth OpenClaw Codex eksplisit untuk agen. +2. Akun app-server yang sudah ada di home Codex agen tersebut. 3. Hanya untuk peluncuran app-server stdio lokal, `CODEX_API_KEY`, lalu `OPENAI_API_KEY`, saat tidak ada akun app-server dan auth OpenAI masih diperlukan. -Saat OpenClaw melihat profil auth Codex bergaya langganan ChatGPT, OpenClaw menghapus +Saat OpenClaw melihat profil auth Codex bergaya langganan ChatGPT, ia menghapus `CODEX_API_KEY` dan `OPENAI_API_KEY` dari proses anak Codex yang di-spawn. Itu -menjaga kunci API tingkat Gateway tetap tersedia untuk embedding atau model OpenAI langsung -tanpa membuat giliran app-server Codex native secara tidak sengaja ditagih melalui API. -Profil kunci API Codex eksplisit dan fallback kunci env stdio lokal menggunakan login app-server +membuat kunci API tingkat Gateway tetap tersedia untuk embedding atau model OpenAI langsung +tanpa membuat giliran app-server native Codex tertagih melalui API tanpa sengaja. +Profil kunci API Codex eksplisit dan fallback env-key stdio lokal menggunakan login app-server alih-alih env proses anak yang diwarisi. Koneksi app-server WebSocket -tidak menerima fallback kunci API env Gateway; gunakan profil auth eksplisit atau akun milik -app-server remote. +tidak menerima fallback kunci API env Gateway; gunakan profil auth eksplisit atau +akun milik app-server jarak jauh sendiri. -Jika sebuah deployment memerlukan isolasi lingkungan tambahan, tambahkan variabel tersebut ke +Jika deployment membutuhkan isolasi lingkungan tambahan, tambahkan variabel tersebut ke `appServer.clearEnv`: ```json5 @@ -556,36 +584,35 @@ Jika sebuah deployment memerlukan isolasi lingkungan tambahan, tambahkan variabe Field `appServer` yang didukung: -| Bidang | Default | Arti | -| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` menjalankan Codex; `"websocket"` terhubung ke `url`. | -| `command` | biner Codex terkelola | Executable untuk transport stdio. Biarkan tidak disetel untuk menggunakan biner terkelola; setel hanya untuk penggantian eksplisit. | -| `args` | `["app-server", "--listen", "stdio://"]` | Argumen untuk transport stdio. | -| `url` | tidak disetel | URL app-server WebSocket. | -| `authToken` | tidak disetel | Token bearer untuk transport WebSocket. | -| `headers` | `{}` | Header WebSocket tambahan. | -| `clearEnv` | `[]` | Nama variabel lingkungan tambahan yang dihapus dari proses app-server stdio yang dijalankan setelah OpenClaw membangun lingkungan turunan. | -| `requestTimeoutMs` | `60000` | Timeout untuk panggilan bidang kontrol app-server. | -| `mode` | `"yolo"` | Preset untuk eksekusi YOLO atau yang ditinjau guardian. | -| `approvalPolicy` | `"never"` | Kebijakan persetujuan native Codex yang dikirim ke thread start/resume/turn. | -| `sandbox` | `"danger-full-access"` | Mode sandbox native Codex yang dikirim ke thread start/resume. | -| `approvalsReviewer` | `"user"` | Gunakan `"auto_review"` agar Codex meninjau prompt persetujuan native. `guardian_subagent` tetap merupakan alias lama. | -| `serviceTier` | tidak disetel | Tingkat layanan app-server Codex opsional: `"fast"`, `"flex"`, atau `null`. Nilai lama yang tidak valid diabaikan. | +| Bidang | Default | Makna | +| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` menjalankan Codex; `"websocket"` terhubung ke `url`. | +| `command` | biner Codex terkelola | Executable untuk transport stdio. Biarkan tidak diatur untuk menggunakan biner terkelola; atur hanya untuk override eksplisit. | +| `args` | `["app-server", "--listen", "stdio://"]` | Argumen untuk transport stdio. | +| `url` | tidak diatur | URL app-server WebSocket. | +| `authToken` | tidak diatur | Token bearer untuk transport WebSocket. | +| `headers` | `{}` | Header WebSocket tambahan. | +| `clearEnv` | `[]` | Nama variabel lingkungan tambahan yang dihapus dari proses app-server stdio yang dijalankan setelah OpenClaw membangun lingkungan warisannya. `CODEX_HOME` dan `HOME` dicadangkan untuk isolasi Codex per agen milik OpenClaw pada peluncuran lokal. | +| `requestTimeoutMs` | `60000` | Timeout untuk panggilan bidang kontrol app-server. | +| `mode` | `"yolo"` | Preset untuk eksekusi YOLO atau yang ditinjau guardian. | +| `approvalPolicy` | `"never"` | Kebijakan persetujuan native Codex yang dikirim ke mulai/lanjutkan/turn thread. | +| `sandbox` | `"danger-full-access"` | Mode sandbox native Codex yang dikirim ke mulai/lanjutkan thread. | +| `approvalsReviewer` | `"user"` | Gunakan `"auto_review"` agar Codex meninjau prompt persetujuan native. `guardian_subagent` tetap menjadi alias lama. | +| `serviceTier` | tidak diatur | Tingkat layanan app-server Codex opsional: `"fast"`, `"flex"`, atau `null`. Nilai lama yang tidak valid diabaikan. | Panggilan alat dinamis milik OpenClaw dibatasi secara independen dari `appServer.requestTimeoutMs`: setiap permintaan Codex `item/tool/call` harus menerima respons OpenClaw dalam 30 detik. Saat timeout, OpenClaw membatalkan sinyal alat jika didukung dan mengembalikan respons alat dinamis yang gagal ke Codex agar -turn dapat berlanjut alih-alih membiarkan sesi berada dalam `processing`. +turn dapat berlanjut alih-alih membiarkan sesi dalam status `processing`. -Setelah OpenClaw merespons permintaan app-server berskala turn dari Codex, harness -juga mengharapkan Codex menyelesaikan turn native dengan `turn/completed`. Jika -app-server tidak merespons selama 60 detik setelah respons tersebut, OpenClaw -sebisa mungkin menginterupsi turn Codex, mencatat timeout diagnostik, dan -melepaskan lane sesi OpenClaw agar pesan chat lanjutan tidak mengantre di belakang -turn native yang basi. +Setelah OpenClaw merespons permintaan app-server dengan cakupan turn dari Codex, +harness juga mengharapkan Codex menyelesaikan turn native dengan `turn/completed`. Jika +app-server diam selama 60 detik setelah respons tersebut, OpenClaw dengan upaya terbaik +menginterupsi turn Codex, mencatat timeout diagnostik, dan melepaskan jalur sesi +OpenClaw agar pesan chat lanjutan tidak mengantre di belakang turn native yang usang. -Penggantian lingkungan tetap tersedia untuk pengujian lokal: +Override lingkungan tetap tersedia untuk pengujian lokal: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -593,22 +620,22 @@ Penggantian lingkungan tetap tersedia untuk pengujian lokal: - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` melewati biner terkelola ketika -`appServer.command` tidak disetel. +`OPENCLAW_CODEX_APP_SERVER_BIN` melewati biner terkelola saat +`appServer.command` tidak diatur. `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` telah dihapus. Gunakan `plugins.entries.codex.config.appServer.mode: "guardian"` sebagai gantinya, atau -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` untuk pengujian lokal sekali pakai. Konfigurasi -lebih disarankan untuk deployment yang dapat diulang karena menjaga perilaku plugin -dalam file yang sama-sama ditinjau seperti sisa penyiapan harness Codex. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` untuk pengujian lokal satu kali. Konfigurasi +lebih disarankan untuk deployment yang dapat diulang karena menjaga perilaku plugin di +file yang sama-sama ditinjau dengan sisa penyiapan harness Codex. ## Penggunaan komputer Penggunaan Komputer dibahas dalam panduan penyiapannya sendiri: [Penggunaan Komputer Codex](/id/plugins/codex-computer-use). -Versi singkatnya: OpenClaw tidak menyertakan aplikasi kontrol desktop sebagai vendor atau menjalankan -aksi desktop sendiri. OpenClaw menyiapkan app-server Codex, memverifikasi bahwa server MCP +Versi singkatnya: OpenClaw tidak menyertakan app kontrol desktop sebagai vendor atau mengeksekusi +tindakan desktop sendiri. OpenClaw menyiapkan app-server Codex, memverifikasi bahwa server MCP `computer-use` tersedia, lalu membiarkan Codex menangani panggilan alat MCP native selama turn mode Codex. @@ -653,18 +680,18 @@ Penyiapan dapat diperiksa atau diinstal dari permukaan perintah: - `/codex computer-use install --marketplace-path ` Penggunaan Komputer khusus macOS dan mungkin memerlukan izin OS lokal sebelum -server MCP Codex dapat mengontrol aplikasi. Jika `computerUse.enabled` bernilai true dan server MCP +server MCP Codex dapat mengontrol app. Jika `computerUse.enabled` bernilai true dan server MCP tidak tersedia, turn mode Codex gagal sebelum thread dimulai alih-alih berjalan diam-diam tanpa alat Penggunaan Komputer native. Lihat [Penggunaan Komputer Codex](/id/plugins/codex-computer-use) untuk pilihan marketplace, batas katalog jarak jauh, alasan status, dan pemecahan masalah. -Ketika `computerUse.autoInstall` bernilai true, OpenClaw dapat mendaftarkan marketplace -Codex Desktop bawaan standar dari +Saat `computerUse.autoInstall` bernilai true, OpenClaw dapat mendaftarkan marketplace +Codex Desktop standar bawaan dari `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` jika Codex belum menemukan marketplace lokal. Gunakan `/new` atau `/reset` setelah -mengubah konfigurasi runtime atau Penggunaan Komputer agar sesi yang ada tidak mempertahankan -binding thread PI atau Codex lama. +mengubah konfigurasi runtime atau Penggunaan Komputer agar sesi yang sudah ada tidak mempertahankan +binding PI atau thread Codex lama. ## Resep umum @@ -749,113 +776,73 @@ App-server jarak jauh dengan header eksplisit: } ``` -Peralihan model tetap dikendalikan OpenClaw. Ketika sesi OpenClaw dilampirkan +Pergantian model tetap dikontrol OpenClaw. Saat sesi OpenClaw dilampirkan ke thread Codex yang sudah ada, turn berikutnya mengirim model OpenAI, -provider, kebijakan persetujuan, sandbox, dan tingkat layanan yang sedang dipilih ke +penyedia, kebijakan persetujuan, sandbox, dan tingkat layanan yang sedang dipilih ke app-server lagi. Beralih dari `openai/gpt-5.5` ke `openai/gpt-5.2` mempertahankan binding thread tetapi meminta Codex melanjutkan dengan model yang baru dipilih. ## Perintah Codex Plugin bawaan mendaftarkan `/codex` sebagai perintah slash resmi. Perintah ini -generik dan berfungsi pada channel apa pun yang mendukung perintah teks OpenClaw. +generik dan berfungsi di channel mana pun yang mendukung perintah teks OpenClaw. Bentuk umum: -- `/codex status` menampilkan konektivitas app-server langsung, model, akun, batas laju, server MCP, dan skills. +- `/codex status` menampilkan konektivitas app-server langsung, model, akun, batas laju, server MCP, dan Skills. - `/codex models` mencantumkan model app-server Codex langsung. - `/codex threads [filter]` mencantumkan thread Codex terbaru. - `/codex resume ` melampirkan sesi OpenClaw saat ini ke thread Codex yang sudah ada. -- `/codex compact` meminta app-server Codex memadatkan thread yang terlampir. -- `/codex review` memulai tinjauan native Codex untuk thread yang terlampir. -- `/codex diagnostics [note]` meminta izin sebelum mengirim umpan balik diagnostik Codex untuk thread yang terlampir. +- `/codex compact` meminta app-server Codex memadatkan thread terlampir. +- `/codex review` memulai peninjauan native Codex untuk thread terlampir. +- `/codex diagnostics [note]` meminta konfirmasi sebelum mengirim umpan balik diagnostik Codex untuk thread terlampir. - `/codex computer-use status` memeriksa plugin Penggunaan Komputer dan server MCP yang dikonfigurasi. - `/codex computer-use install` menginstal plugin Penggunaan Komputer yang dikonfigurasi dan memuat ulang server MCP. - `/codex account` menampilkan status akun dan batas laju. - `/codex mcp` mencantumkan status server MCP app-server Codex. -- `/codex skills` mencantumkan skills app-server Codex. +- `/codex skills` mencantumkan Skills app-server Codex. ### Alur kerja debugging umum -Ketika agen berbasis Codex melakukan sesuatu yang mengejutkan di Telegram, Discord, Slack, +Saat agen berbasis Codex melakukan sesuatu yang mengejutkan di Telegram, Discord, Slack, atau channel lain, mulai dari percakapan tempat masalah terjadi: 1. Jalankan `/diagnostics bad tool choice after image upload` atau catatan singkat lain yang menjelaskan apa yang Anda lihat. -2. Setujui permintaan diagnostik satu kali. Persetujuan tersebut membuat zip diagnostik Gateway - lokal dan, karena sesi menggunakan harness Codex, juga mengirim bundle umpan balik Codex - yang relevan ke server OpenAI. +2. Setujui permintaan diagnostik sekali. Persetujuan membuat zip diagnostik Gateway + lokal dan, karena sesi menggunakan harness Codex, juga + mengirim bundel umpan balik Codex yang relevan ke server OpenAI. 3. Salin balasan diagnostik yang selesai ke laporan bug atau thread dukungan. - Balasan tersebut menyertakan path bundle lokal, ringkasan privasi, id sesi OpenClaw, + Balasan tersebut menyertakan jalur bundel lokal, ringkasan privasi, id sesi OpenClaw, id thread Codex, dan baris `Inspect locally` untuk setiap thread Codex. 4. Jika Anda ingin men-debug run sendiri, jalankan perintah `Inspect locally` - yang dicetak di terminal. Bentuknya seperti `codex resume ` dan membuka - thread Codex native sehingga Anda dapat memeriksa percakapan, melanjutkannya secara lokal, + yang dicetak di terminal. Perintahnya terlihat seperti `codex resume ` dan membuka + thread Codex native agar Anda dapat memeriksa percakapan, melanjutkannya secara lokal, atau bertanya kepada Codex mengapa memilih alat atau rencana tertentu. -Gunakan `/codex diagnostics [note]` hanya ketika Anda secara khusus menginginkan upload -umpan balik Codex untuk thread yang saat ini terlampir tanpa bundle diagnostik -Gateway OpenClaw lengkap. Untuk sebagian besar laporan dukungan, `/diagnostics [note]` adalah -titik awal yang lebih baik karena mengikat status Gateway lokal dan id thread Codex -bersama-sama dalam satu balasan. Lihat [Ekspor diagnostik](/id/gateway/diagnostics) -untuk model privasi lengkap dan perilaku chat grup. +Gunakan `/codex diagnostics [note]` hanya ketika Anda secara khusus menginginkan unggahan umpan balik Codex untuk thread yang saat ini terlampir tanpa bundel diagnostik Gateway OpenClaw penuh. Untuk sebagian besar laporan dukungan, `/diagnostics [note]` adalah titik awal yang lebih baik karena mengikat status Gateway lokal dan id thread Codex bersama-sama dalam satu balasan. Lihat [Ekspor diagnostik](/id/gateway/diagnostics) untuk model privasi lengkap dan perilaku obrolan grup. -Core OpenClaw juga mengekspos `/diagnostics [note]` khusus owner sebagai perintah diagnostik -Gateway umum. Prompt persetujuannya menampilkan pembuka data sensitif, -menautkan ke [Ekspor Diagnostik](/id/gateway/diagnostics), dan meminta -`openclaw gateway diagnostics export --json` melalui persetujuan exec eksplisit -setiap kali. Jangan setujui diagnostik dengan aturan izinkan-semua. Setelah persetujuan, -OpenClaw mengirim laporan yang dapat ditempel dengan path bundle lokal dan ringkasan -manifes. Ketika sesi OpenClaw aktif menggunakan harness Codex, persetujuan yang -sama juga mengotorisasi pengiriman bundle umpan balik Codex yang relevan ke -server OpenAI. Prompt persetujuan menyatakan bahwa umpan balik Codex akan dikirim, tetapi -tidak mencantumkan id sesi atau thread Codex sebelum persetujuan. +Inti OpenClaw juga mengekspos `/diagnostics [note]` khusus pemilik sebagai perintah diagnostik Gateway umum. Prompt persetujuannya menampilkan pembuka data sensitif, menautkan ke [Ekspor Diagnostik](/id/gateway/diagnostics), dan meminta `openclaw gateway diagnostics export --json` melalui persetujuan eksekusi eksplisit setiap kali. Jangan menyetujui diagnostik dengan aturan izinkan-semua. Setelah disetujui, OpenClaw mengirim laporan yang dapat ditempel dengan jalur bundel lokal dan ringkasan manifes. Ketika sesi OpenClaw aktif menggunakan harness Codex, persetujuan yang sama juga mengizinkan pengiriman bundel umpan balik Codex yang relevan ke server OpenAI. Prompt persetujuan menyatakan bahwa umpan balik Codex akan dikirim, tetapi tidak mencantumkan id sesi atau thread Codex sebelum persetujuan. -Jika `/diagnostics` dipanggil oleh owner dalam chat grup, OpenClaw menjaga -channel bersama tetap bersih: grup hanya menerima pemberitahuan singkat, sedangkan -pembuka diagnostik, prompt persetujuan, dan id sesi/thread Codex dikirim ke -owner melalui rute persetujuan pribadi. Jika tidak ada rute owner pribadi, -OpenClaw menolak permintaan grup dan meminta owner menjalankannya dari DM. +Jika `/diagnostics` dipanggil oleh pemilik dalam obrolan grup, OpenClaw menjaga kanal bersama tetap bersih: grup hanya menerima pemberitahuan singkat, sementara pembuka diagnostik, prompt persetujuan, dan id sesi/thread Codex dikirim ke pemilik melalui rute persetujuan privat. Jika tidak ada rute pemilik privat, OpenClaw menolak permintaan grup dan meminta pemilik menjalankannya dari DM. -Unggahan Codex yang disetujui memanggil `feedback/upload` app-server Codex dan meminta -app-server menyertakan log untuk setiap thread yang tercantum dan subthread Codex -yang dibuat saat tersedia. Unggahan berjalan melalui jalur umpan balik normal -Codex ke server OpenAI; jika umpan balik Codex dinonaktifkan di app-server itu, -perintah mengembalikan kesalahan app-server. Balasan diagnostik yang selesai -mencantumkan channel, id sesi OpenClaw, id thread Codex, dan perintah lokal -`codex resume ` untuk thread yang dikirim. Jika Anda menolak atau -mengabaikan persetujuan, OpenClaw tidak mencetak id Codex tersebut. Unggahan ini -tidak menggantikan ekspor diagnostik Gateway lokal. +Unggahan Codex yang disetujui memanggil `feedback/upload` app-server Codex dan meminta app-server menyertakan log untuk setiap thread yang tercantum dan subthread Codex yang dibuat bila tersedia. Unggahan melewati jalur umpan balik normal Codex ke server OpenAI; jika umpan balik Codex dinonaktifkan di app-server tersebut, perintah mengembalikan kesalahan app-server. Balasan diagnostik yang selesai mencantumkan kanal, id sesi OpenClaw, id thread Codex, dan perintah lokal `codex resume ` untuk thread yang dikirim. Jika Anda menolak atau mengabaikan persetujuan, OpenClaw tidak mencetak id Codex tersebut. Unggahan ini tidak menggantikan ekspor diagnostik Gateway lokal. -`/codex resume` menulis file binding sidecar yang sama dengan yang digunakan -harness untuk giliran normal. Pada pesan berikutnya, OpenClaw melanjutkan thread -Codex tersebut, meneruskan model OpenClaw yang saat ini dipilih ke app-server, -dan menjaga riwayat panjang tetap aktif. +`/codex resume` menulis berkas sidecar binding yang sama dengan yang digunakan harness untuk giliran normal. Pada pesan berikutnya, OpenClaw melanjutkan thread Codex tersebut, meneruskan model OpenClaw yang saat ini dipilih ke app-server, dan menjaga riwayat yang diperluas tetap aktif. -### Memeriksa thread Codex dari CLI +### Periksa thread Codex dari CLI -Cara tercepat untuk memahami proses Codex yang buruk sering kali adalah membuka -thread Codex native secara langsung: +Cara tercepat untuk memahami eksekusi Codex yang buruk sering kali adalah membuka thread Codex native secara langsung: ```sh codex resume ``` -Gunakan ini saat Anda menemukan bug dalam percakapan channel dan ingin memeriksa -sesi Codex yang bermasalah, melanjutkannya secara lokal, atau bertanya kepada -Codex mengapa ia membuat pilihan alat atau penalaran tertentu. Jalur termudah -biasanya menjalankan `/diagnostics [note]` terlebih dahulu: setelah Anda -menyetujuinya, laporan yang selesai mencantumkan setiap thread Codex dan mencetak -perintah `Inspect locally`, misalnya `codex resume `. Anda dapat -menyalin perintah itu langsung ke terminal. +Gunakan ini ketika Anda melihat bug dalam percakapan kanal dan ingin memeriksa sesi Codex yang bermasalah, melanjutkannya secara lokal, atau bertanya kepada Codex mengapa ia membuat pilihan alat atau penalaran tertentu. Jalur termudah biasanya menjalankan `/diagnostics [note]` terlebih dahulu: setelah Anda menyetujuinya, laporan yang selesai mencantumkan setiap thread Codex dan mencetak perintah `Periksa secara lokal`, misalnya `codex resume `. Anda dapat menyalin perintah itu langsung ke terminal. -Anda juga dapat memperoleh id thread dari `/codex binding` untuk chat saat ini -atau `/codex threads [filter]` untuk thread app-server Codex terbaru, lalu -menjalankan perintah `codex resume` yang sama di shell Anda. +Anda juga dapat memperoleh id thread dari `/codex binding` untuk obrolan saat ini atau `/codex threads [filter]` untuk thread app-server Codex terbaru, lalu menjalankan perintah `codex resume` yang sama di shell Anda. -Permukaan perintah memerlukan app-server Codex `0.125.0` atau yang lebih baru. -Metode kontrol individual dilaporkan sebagai `unsupported by this Codex app-server` -jika app-server mendatang atau kustom tidak mengekspos metode JSON-RPC tersebut. +Permukaan perintah memerlukan app-server Codex `0.125.0` atau yang lebih baru. Metode kontrol individual dilaporkan sebagai `unsupported by this Codex app-server` jika app-server masa depan atau kustom tidak mengekspos metode JSON-RPC tersebut. ## Batas hook @@ -863,164 +850,149 @@ Harness Codex memiliki tiga lapisan hook: | Lapisan | Pemilik | Tujuan | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| Hook Plugin OpenClaw | OpenClaw | Kompatibilitas produk/Plugin lintas harness PI dan Codex. | -| Middleware ekstensi app-server Codex | Plugin bawaan OpenClaw | Perilaku adaptor per giliran di sekitar alat dinamis OpenClaw. | +| Hook Plugin OpenClaw | OpenClaw | Kompatibilitas produk/Plugin di seluruh harness PI dan Codex. | +| Middleware ekstensi app-server Codex | Plugin bawaan OpenClaw | Perilaku adapter per-giliran di sekitar alat dinamis OpenClaw. | | Hook native Codex | Codex | Siklus hidup Codex tingkat rendah dan kebijakan alat native dari konfigurasi Codex. | -OpenClaw tidak menggunakan file `hooks.json` proyek atau global Codex untuk -merutekan perilaku Plugin OpenClaw. Untuk jembatan alat native dan izin yang -didukung, OpenClaw menyuntikkan konfigurasi Codex per thread untuk `PreToolUse`, -`PostToolUse`, `PermissionRequest`, dan `Stop`. Hook Codex lain seperti -`SessionStart` dan `UserPromptSubmit` tetap merupakan kontrol tingkat Codex; -keduanya tidak diekspos sebagai hook Plugin OpenClaw dalam kontrak v1. +OpenClaw tidak menggunakan berkas `hooks.json` proyek atau global Codex untuk merutekan perilaku Plugin OpenClaw. Untuk jembatan alat native dan izin yang didukung, OpenClaw menyuntikkan konfigurasi Codex per-thread untuk `PreToolUse`, `PostToolUse`, `PermissionRequest`, dan `Stop`. Hook Codex lain seperti `SessionStart` dan `UserPromptSubmit` tetap menjadi kontrol tingkat Codex; hook tersebut tidak diekspos sebagai hook Plugin OpenClaw dalam kontrak v1. -Untuk alat dinamis OpenClaw, OpenClaw menjalankan alat setelah Codex meminta -panggilan tersebut, sehingga OpenClaw memicu perilaku Plugin dan middleware yang -dimilikinya di adaptor harness. Untuk alat native Codex, Codex memiliki catatan -alat kanonis. OpenClaw dapat mencerminkan event tertentu, tetapi tidak dapat -menulis ulang thread Codex native kecuali Codex mengekspos operasi tersebut -melalui app-server atau callback hook native. +Untuk alat dinamis OpenClaw, OpenClaw mengeksekusi alat setelah Codex meminta panggilan, sehingga OpenClaw menjalankan perilaku Plugin dan middleware yang dimilikinya dalam adapter harness. Untuk alat native Codex, Codex memiliki catatan alat kanonis. OpenClaw dapat mencerminkan peristiwa tertentu, tetapi tidak dapat menulis ulang thread Codex native kecuali Codex mengekspos operasi tersebut melalui app-server atau callback hook native. -Proyeksi siklus hidup Compaction dan LLM berasal dari notifikasi app-server -Codex dan status adaptor OpenClaw, bukan perintah hook native Codex. Event -`before_compaction`, `after_compaction`, `llm_input`, dan `llm_output` milik -OpenClaw adalah observasi tingkat adaptor, bukan tangkapan byte demi byte dari -permintaan internal Codex atau payload Compaction. +Proyeksi Compaction dan siklus hidup LLM berasal dari notifikasi app-server Codex dan status adapter OpenClaw, bukan perintah hook native Codex. Peristiwa `before_compaction`, `after_compaction`, `llm_input`, dan `llm_output` OpenClaw adalah observasi tingkat adapter, bukan tangkapan byte-demi-byte dari permintaan internal atau payload Compaction Codex. -Notifikasi app-server `hook/started` dan `hook/completed` native Codex -diproyeksikan sebagai event agen `codex_app_server.hook` untuk trajektori dan -debugging. Keduanya tidak memanggil hook Plugin OpenClaw. +Notifikasi app-server `hook/started` dan `hook/completed` native Codex diproyeksikan sebagai peristiwa agen `codex_app_server.hook` untuk trajectory dan debugging. Notifikasi tersebut tidak memanggil hook Plugin OpenClaw. ## Kontrak dukungan V1 -Mode Codex bukan PI dengan panggilan model berbeda di bawahnya. Codex memiliki -lebih banyak bagian dari loop model native, dan OpenClaw menyesuaikan permukaan -Plugin dan sesinya di sekitar batas tersebut. +Mode Codex bukan PI dengan panggilan model berbeda di bawahnya. Codex memiliki lebih banyak loop model native, dan OpenClaw mengadaptasi permukaan Plugin dan sesi di sekitar batas tersebut. -Didukung di runtime Codex v1: +Didukung dalam runtime Codex v1: -| Permukaan | Dukungan | Alasan | +| Permukaan | Dukungan | Mengapa | | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Loop model OpenAI melalui Codex | Didukung | App-server Codex memiliki giliran OpenAI, pelanjutan thread native, dan kelanjutan alat native. | -| Perutean dan pengiriman channel OpenClaw | Didukung | Telegram, Discord, Slack, WhatsApp, iMessage, dan channel lain tetap berada di luar runtime model. | -| Alat dinamis OpenClaw | Didukung | Codex meminta OpenClaw menjalankan alat ini, sehingga OpenClaw tetap berada di jalur eksekusi. | +| Perutean dan pengiriman kanal OpenClaw | Didukung | Telegram, Discord, Slack, WhatsApp, iMessage, dan kanal lain tetap berada di luar runtime model. | +| Alat dinamis OpenClaw | Didukung | Codex meminta OpenClaw mengeksekusi alat ini, sehingga OpenClaw tetap berada di jalur eksekusi. | | Plugin prompt dan konteks | Didukung | OpenClaw membangun overlay prompt dan memproyeksikan konteks ke giliran Codex sebelum memulai atau melanjutkan thread. | -| Siklus hidup mesin konteks | Didukung | Perakitan, ingest atau pemeliharaan setelah giliran, dan koordinasi Compaction mesin konteks berjalan untuk giliran Codex. | +| Siklus hidup mesin konteks | Didukung | Perakitan, ingest atau pemeliharaan pasca-giliran, dan koordinasi Compaction mesin konteks berjalan untuk giliran Codex. | | Hook alat dinamis | Didukung | `before_tool_call`, `after_tool_call`, dan middleware hasil alat berjalan di sekitar alat dinamis milik OpenClaw. | -| Hook siklus hidup | Didukung sebagai observasi adaptor | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, dan `after_compaction` dipicu dengan payload mode Codex yang jujur. | -| Gerbang revisi jawaban akhir | Didukung melalui relay hook native | `Stop` Codex diteruskan ke `before_agent_finalize`; `revise` meminta Codex melakukan satu lintasan model lagi sebelum finalisasi. | -| Blokir atau observasi shell, patch, dan MCP native | Didukung melalui relay hook native | `PreToolUse` dan `PostToolUse` Codex diteruskan untuk permukaan alat native yang sudah dikomit, termasuk payload MCP pada app-server Codex `0.125.0` atau yang lebih baru. Pemblokiran didukung; penulisan ulang argumen tidak. | -| Kebijakan izin native | Didukung melalui relay hook native | `PermissionRequest` Codex dapat dirutekan melalui kebijakan OpenClaw saat runtime mengeksposnya. Jika OpenClaw tidak mengembalikan keputusan, Codex melanjutkan melalui guardian normalnya atau jalur persetujuan pengguna. | -| Tangkapan trajektori app-server | Didukung | OpenClaw merekam permintaan yang dikirimnya ke app-server dan notifikasi app-server yang diterimanya. | +| Hook siklus hidup | Didukung sebagai observasi adapter | `llm_input`, `llm_output`, `agent_end`, `before_compaction`, dan `after_compaction` berjalan dengan payload mode Codex yang jujur. | +| Gerbang revisi jawaban akhir | Didukung melalui relay hook native | `Stop` Codex direlay ke `before_agent_finalize`; `revise` meminta Codex melakukan satu lintasan model lagi sebelum finalisasi. | +| Blokir atau observasi shell, patch, dan MCP native | Didukung melalui relay hook native | `PreToolUse` dan `PostToolUse` Codex direlay untuk permukaan alat native yang telah dikomit, termasuk payload MCP pada app-server Codex `0.125.0` atau yang lebih baru. Pemblokiran didukung; penulisan ulang argumen tidak. | +| Kebijakan izin native | Didukung melalui relay hook native | `PermissionRequest` Codex dapat dirutekan melalui kebijakan OpenClaw ketika runtime mengeksposnya. Jika OpenClaw tidak mengembalikan keputusan, Codex melanjutkan melalui guardian normal atau jalur persetujuan pengguna. | +| Penangkapan trajectory app-server | Didukung | OpenClaw merekam permintaan yang dikirimnya ke app-server dan notifikasi app-server yang diterimanya. | -Tidak didukung di runtime Codex v1: +Tidak didukung dalam runtime Codex v1: -| Permukaan | Batas V1 | Jalur mendatang | -| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Mutasi argumen alat native | Hook pra-alat native Codex dapat memblokir, tetapi OpenClaw tidak menulis ulang argumen alat native Codex. | Memerlukan dukungan hook/skema Codex untuk input alat pengganti. | -| Riwayat transkrip native Codex yang dapat diedit | Codex memiliki riwayat thread native kanonis. OpenClaw memiliki cermin dan dapat memproyeksikan konteks mendatang, tetapi tidak boleh memutasi internal yang tidak didukung. | Tambahkan API app-server Codex eksplisit jika operasi thread native diperlukan. | -| `tool_result_persist` untuk catatan alat native Codex | Hook tersebut mentransformasi penulisan transkrip milik OpenClaw, bukan catatan alat native Codex. | Dapat mencerminkan catatan yang ditransformasi, tetapi penulisan ulang kanonis memerlukan dukungan Codex. | -| Metadata Compaction native yang kaya | OpenClaw mengamati awal dan penyelesaian Compaction, tetapi tidak menerima daftar tersimpan/dibuang yang stabil, delta token, atau payload ringkasan. | Memerlukan event Compaction Codex yang lebih kaya. | -| Intervensi Compaction | Hook Compaction OpenClaw saat ini berada di tingkat notifikasi dalam mode Codex. | Tambahkan hook Compaction pra/pasca Codex jika Plugin perlu memveto atau menulis ulang Compaction native. | -| Tangkapan permintaan API model byte demi byte | OpenClaw dapat menangkap permintaan dan notifikasi app-server, tetapi inti Codex membangun permintaan API OpenAI akhir secara internal. | Memerlukan event pelacakan permintaan model Codex atau API debug. | +| Permukaan | Batas V1 | Jalur masa depan | +| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Mutasi argumen alat native | Hook pra-alat native Codex dapat memblokir, tetapi OpenClaw tidak menulis ulang argumen alat native Codex. | Memerlukan dukungan hook/skema Codex untuk input alat pengganti. | +| Riwayat transkrip native Codex yang dapat diedit | Codex memiliki riwayat thread native kanonis. OpenClaw memiliki cermin dan dapat memproyeksikan konteks mendatang, tetapi tidak boleh memutasi internal yang tidak didukung. | Tambahkan API server aplikasi Codex eksplisit jika pembedahan thread native diperlukan. | +| `tool_result_persist` untuk catatan alat native Codex | Hook itu mengubah penulisan transkrip milik OpenClaw, bukan catatan alat native Codex. | Dapat mencerminkan catatan yang telah diubah, tetapi penulisan ulang kanonis membutuhkan dukungan Codex. | +| Metadata compaction native yang kaya | OpenClaw mengamati awal dan penyelesaian compaction, tetapi tidak menerima daftar stabil yang dipertahankan/dibuang, delta token, atau payload ringkasan. | Membutuhkan event compaction Codex yang lebih kaya. | +| Intervensi compaction | Hook compaction OpenClaw saat ini berada pada tingkat notifikasi dalam mode Codex. | Tambahkan hook pra/pasca compaction Codex jika plugin perlu memveto atau menulis ulang compaction native. | +| Penangkapan permintaan API model byte-demi-byte | OpenClaw dapat menangkap permintaan dan notifikasi server aplikasi, tetapi inti Codex membangun permintaan API OpenAI final secara internal. | Membutuhkan event pelacakan permintaan model Codex atau API debug. | -## Alat, media, dan Compaction +## Alat, media, dan compaction Harness Codex hanya mengubah eksekutor agen tertanam tingkat rendah. OpenClaw tetap membangun daftar alat dan menerima hasil alat dinamis dari harness. Teks, gambar, video, musik, TTS, persetujuan, dan output alat pesan -tetap berjalan melalui jalur pengiriman OpenClaw normal. +tetap melalui jalur pengiriman OpenClaw normal. -Relay hook native sengaja dibuat generik, tetapi kontrak dukungan v1 terbatas -pada jalur alat native Codex dan izin yang diuji OpenClaw. Dalam runtime Codex, -itu mencakup payload shell, patch, dan MCP `PreToolUse`, `PostToolUse`, dan -`PermissionRequest`. Jangan berasumsi bahwa setiap event hook Codex di masa depan -adalah permukaan Plugin OpenClaw sampai kontrak runtime menamainya. +Relay hook native sengaja dibuat generik, tetapi kontrak dukungan v1 +dibatasi pada jalur alat dan izin native Codex yang diuji OpenClaw. Dalam +runtime Codex, itu mencakup payload shell, patch, dan MCP `PreToolUse`, +`PostToolUse`, serta `PermissionRequest`. Jangan menganggap setiap event hook +Codex di masa depan sebagai permukaan plugin OpenClaw sampai kontrak runtime +menamakannya. Untuk `PermissionRequest`, OpenClaw hanya mengembalikan keputusan izinkan atau -tolak yang eksplisit saat kebijakan memutuskan. Hasil tanpa keputusan bukan -izin. Codex memperlakukannya sebagai tidak ada keputusan hook dan jatuh ke -guardian miliknya sendiri atau jalur persetujuan pengguna. +tolak eksplisit ketika kebijakan memutuskan. Hasil tanpa keputusan bukanlah +izin. Codex memperlakukannya sebagai tidak ada keputusan hook dan meneruskan ke +jalur guardian atau persetujuan penggunanya sendiri. -Elisitasi persetujuan alat MCP Codex dirutekan melalui alur persetujuan Plugin -OpenClaw saat Codex menandai `_meta.codex_approval_kind` sebagai -`"mcp_tool_call"`. Prompt `request_user_input` Codex dikirim kembali ke chat asal, -dan pesan tindak lanjut antrean berikutnya menjawab permintaan server native itu -alih-alih diarahkan sebagai konteks tambahan. Permintaan elisitasi MCP lainnya -tetap gagal tertutup. +Elisitasi persetujuan alat MCP Codex dirutekan melalui alur persetujuan plugin +OpenClaw ketika Codex menandai `_meta.codex_approval_kind` sebagai +`"mcp_tool_call"`. Prompt `request_user_input` Codex dikirim kembali ke chat +asal, dan pesan tindak lanjut berikutnya yang mengantre menjawab permintaan +server native itu alih-alih diarahkan sebagai konteks tambahan. Permintaan +elisitasi MCP lain tetap gagal tertutup. -Pengarahan antrean active-run dipetakan ke Codex app-server `turn/steer`. Dengan -default `messages.queue.mode: "steer"`, OpenClaw mengelompokkan pesan obrolan -yang masuk antrean selama quiet window yang dikonfigurasi dan mengirimkannya -sebagai satu permintaan `turn/steer` dalam urutan kedatangan. Mode `queue` -legacy mengirim permintaan `turn/steer` terpisah. Turn peninjauan Codex dan -Compaction manual dapat menolak pengarahan same-turn, dalam kasus ini -OpenClaw menggunakan antrean followup jika mode yang dipilih mengizinkan fallback. Lihat -[Antrean pengarahan](/id/concepts/queue-steering). +Pengarahan antrean run aktif dipetakan ke `turn/steer` server aplikasi Codex. +Dengan default `messages.queue.mode: "steer"`, OpenClaw mengelompokkan pesan +chat yang mengantre selama jendela tenang yang dikonfigurasi dan mengirimnya +sebagai satu permintaan `turn/steer` sesuai urutan kedatangan. Mode `queue` +lama mengirim permintaan `turn/steer` terpisah. Turn tinjauan Codex dan +compaction manual dapat menolak pengarahan pada turn yang sama, dalam hal ini +OpenClaw menggunakan antrean tindak lanjut ketika mode yang dipilih mengizinkan +fallback. Lihat [Antrean pengarahan](/id/concepts/queue-steering). -Ketika model yang dipilih menggunakan harness Codex, Compaction thread native -didelegasikan ke Codex app-server. OpenClaw mempertahankan cermin transkrip untuk riwayat -channel, pencarian, `/new`, `/reset`, serta peralihan model atau harness di masa depan. Cermin -tersebut mencakup prompt pengguna, teks akhir asisten, dan catatan penalaran atau rencana Codex -yang ringan ketika app-server memancarkannya. Saat ini, OpenClaw hanya -mencatat sinyal mulai dan selesai Compaction native. OpenClaw belum mengekspos -ringkasan Compaction yang dapat dibaca manusia atau daftar teraudit tentang entri mana yang -dipertahankan Codex setelah Compaction. +Ketika model yang dipilih menggunakan harness Codex, compaction thread native +didelegasikan ke server aplikasi Codex. OpenClaw mempertahankan cermin +transkrip untuk riwayat channel, pencarian, `/new`, `/reset`, dan peralihan +model atau harness di masa depan. Cermin itu mencakup prompt pengguna, teks +asisten final, dan catatan penalaran atau rencana Codex yang ringan ketika +server aplikasi memancarkannya. Saat ini, OpenClaw hanya mencatat sinyal awal +dan penyelesaian compaction native. OpenClaw belum mengekspos ringkasan +compaction yang dapat dibaca manusia atau daftar yang dapat diaudit tentang +entri mana yang dipertahankan Codex setelah compaction. -Karena Codex memiliki thread native kanonis, `tool_result_persist` saat ini tidak -menulis ulang catatan hasil tool native Codex. Ini hanya berlaku ketika -OpenClaw menulis hasil tool transkrip sesi milik OpenClaw. +Karena Codex memiliki thread native kanonis, `tool_result_persist` saat ini +tidak menulis ulang catatan hasil alat native Codex. Itu hanya berlaku ketika +OpenClaw menulis hasil alat transkrip sesi milik OpenClaw. -Pembuatan media tidak memerlukan PI. Pemahaman gambar, video, musik, PDF, TTS, dan media -tetap menggunakan pengaturan provider/model yang sesuai seperti +Pembuatan media tidak memerlukan PI. Gambar, video, musik, PDF, TTS, dan +pemahaman media tetap menggunakan pengaturan penyedia/model yang sesuai seperti `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, dan `messages.tts`. ## Pemecahan masalah -**Codex tidak muncul sebagai provider `/model` normal:** itu sesuai ekspektasi untuk -konfigurasi baru. Pilih model `openai/gpt-*` dengan -`agentRuntime.id: "codex"` (atau ref `codex/*` legacy), aktifkan +**Codex tidak muncul sebagai penyedia `/model` normal:** itu memang diharapkan +untuk konfigurasi baru. Pilih model `openai/gpt-*` dengan +`agentRuntime.id: "codex"` (atau ref lama `codex/*`), aktifkan `plugins.entries.codex.enabled`, dan periksa apakah `plugins.allow` mengecualikan `codex`. -**OpenClaw menggunakan PI, bukan Codex:** `agentRuntime.id: "auto"` masih dapat menggunakan PI sebagai +**OpenClaw menggunakan PI alih-alih Codex:** `agentRuntime.id: "auto"` masih dapat menggunakan PI sebagai backend kompatibilitas ketika tidak ada harness Codex yang mengklaim run. Atur `agentRuntime.id: "codex"` untuk memaksa pemilihan Codex saat pengujian. Runtime -Codex yang dipaksa sekarang gagal alih-alih fallback ke PI kecuali Anda -secara eksplisit mengatur `agentRuntime.fallback: "pi"`. Setelah Codex app-server +Codex yang dipaksa kini gagal alih-alih kembali ke PI kecuali Anda secara +eksplisit mengatur `agentRuntime.fallback: "pi"`. Setelah server aplikasi Codex dipilih, kegagalannya muncul langsung tanpa konfigurasi fallback tambahan. -**App-server ditolak:** tingkatkan Codex agar handshake app-server -melaporkan versi `0.125.0` atau lebih baru. Prarilis versi yang sama atau versi bersufiks build -seperti `0.125.0-alpha.2` atau `0.125.0+custom` ditolak karena -floor protokol stabil `0.125.0` adalah yang diuji OpenClaw. +**Server aplikasi ditolak:** tingkatkan Codex agar handshake server aplikasi +melaporkan versi `0.125.0` atau yang lebih baru. Prarilis dengan versi sama atau +versi bersufiks build seperti `0.125.0-alpha.2` atau `0.125.0+custom` ditolak +karena batas bawah protokol stabil `0.125.0` adalah yang diuji OpenClaw. **Penemuan model lambat:** turunkan `plugins.entries.codex.config.discovery.timeoutMs` atau nonaktifkan penemuan. **Transport WebSocket langsung gagal:** periksa `appServer.url`, `authToken`, -dan pastikan app-server jarak jauh berbicara dengan versi protokol Codex app-server yang sama. +dan bahwa server aplikasi jarak jauh menggunakan versi protokol server aplikasi +Codex yang sama. -**Model non-Codex menggunakan PI:** itu sesuai ekspektasi kecuali Anda memaksa -`agentRuntime.id: "codex"` untuk agent tersebut atau memilih ref -`codex/*` legacy. Ref biasa `openai/gpt-*` dan provider lain tetap berada di jalur -provider normalnya dalam mode `auto`. Jika Anda memaksa `agentRuntime.id: "codex"`, setiap turn -tertanam untuk agent tersebut harus berupa model OpenAI yang didukung Codex. +**Model non-Codex menggunakan PI:** itu memang diharapkan kecuali Anda memaksa +`agentRuntime.id: "codex"` untuk agen itu atau memilih ref lama +`codex/*`. Ref `openai/gpt-*` biasa dan penyedia lain tetap berada pada jalur +penyedia normalnya dalam mode `auto`. Jika Anda memaksa `agentRuntime.id: "codex"`, setiap turn tertanam +untuk agen itu harus berupa model OpenAI yang didukung Codex. -**Computer Use terinstal tetapi tool tidak berjalan:** periksa -`/codex computer-use status` dari sesi baru. Jika sebuah tool melaporkan +**Computer Use terpasang tetapi alat tidak berjalan:** periksa +`/codex computer-use status` dari sesi baru. Jika alat melaporkan `Native hook relay unavailable`, gunakan `/new` atau `/reset`; jika tetap terjadi, mulai ulang -gateway untuk membersihkan pendaftaran native hook yang usang. Jika `computer-use.list_apps` +gateway untuk membersihkan pendaftaran hook native yang kedaluwarsa. Jika `computer-use.list_apps` mengalami timeout, mulai ulang Codex Computer Use atau Codex Desktop dan coba lagi. ## Terkait -- [Plugin harness agent](/id/plugins/sdk-agent-harness) -- [Runtime agent](/id/concepts/agent-runtimes) -- [Provider model](/id/concepts/model-providers) -- [Provider OpenAI](/id/providers/openai) +- [Plugin harness agen](/id/plugins/sdk-agent-harness) +- [Runtime agen](/id/concepts/agent-runtimes) +- [Penyedia model](/id/concepts/model-providers) +- [Penyedia OpenAI](/id/providers/openai) - [Status](/id/cli/status) - [Hook plugin](/id/plugins/hooks) - [Referensi konfigurasi](/id/gateway/configuration-reference) diff --git a/docs/id/tools/skills.md b/docs/id/tools/skills.md index 97a2c1584..c6a260610 100644 --- a/docs/id/tools/skills.md +++ b/docs/id/tools/skills.md @@ -2,53 +2,55 @@ read_when: - Menambahkan atau memodifikasi Skills - Mengubah pembatasan Skills, daftar izin, atau aturan pemuatan - - Memahami prioritas Skills dan perilaku cuplikan + - Memahami presedensi Skills dan perilaku cuplikan sidebarTitle: Skills -summary: 'Skills: terkelola vs ruang kerja, aturan pembatasan, daftar izin agen, dan pengkabelan konfigurasi' +summary: 'Skills: terkelola vs ruang kerja, aturan pembatasan, daftar izin agen, dan pengaitan konfigurasi' title: Skills x-i18n: - generated_at: "2026-04-30T10:17:12Z" + generated_at: "2026-04-30T20:05:47Z" model: gpt-5.5 provider: openai - source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a + source_hash: b58d690786756bd3539940aae9f2abcb8a497798ed7b6afeb5e6d6e255fcf257 source_path: tools/skills.md workflow: 16 --- -OpenClaw menggunakan folder keterampilan yang **kompatibel dengan [AgentSkills](https://agentskills.io)** untuk mengajarkan agen cara menggunakan alat. Setiap keterampilan adalah direktori yang berisi `SKILL.md` dengan frontmatter YAML dan instruksi. OpenClaw memuat keterampilan bawaan serta override lokal opsional, lalu memfilternya saat pemuatan berdasarkan lingkungan, konfigurasi, dan keberadaan biner. +OpenClaw menggunakan folder skill yang **kompatibel dengan [AgentSkills](https://agentskills.io)** untuk mengajarkan agen cara menggunakan alat. Setiap skill adalah direktori yang berisi `SKILL.md` dengan frontmatter YAML dan instruksi. OpenClaw memuat skill bawaan ditambah override lokal opsional, lalu memfilternya saat pemuatan berdasarkan lingkungan, konfigurasi, dan keberadaan biner. -## Lokasi dan presedensi +## Lokasi dan prioritas -OpenClaw memuat keterampilan dari sumber berikut, **presedensi tertinggi terlebih dahulu**: +OpenClaw memuat skill dari sumber-sumber ini, **prioritas tertinggi lebih dulu**: -| # | Sumber | Path | -| --- | ------------------------- | -------------------------------- | -| 1 | Keterampilan ruang kerja | `/skills` | -| 2 | Keterampilan agen proyek | `/.agents/skills` | -| 3 | Keterampilan agen pribadi | `~/.agents/skills` | -| 4 | Keterampilan terkelola/lokal | `~/.openclaw/skills` | -| 5 | Keterampilan bawaan | dikirim bersama instalasi | -| 6 | Folder keterampilan tambahan | `skills.load.extraDirs` (konfigurasi) | +| # | Sumber | Jalur | +| --- | --------------------- | -------------------------------- | +| 1 | Skill workspace | `/skills` | +| 2 | Skill agen proyek | `/.agents/skills` | +| 3 | Skill agen pribadi | `~/.agents/skills` | +| 4 | Skill terkelola/lokal | `~/.openclaw/skills` | +| 5 | Skill bawaan | dikirim bersama instalasi | +| 6 | Folder skill ekstra | `skills.load.extraDirs` (config) | -Jika nama keterampilan bentrok, sumber tertinggi yang menang. +Jika nama skill bertentangan, sumber tertinggi yang menang. -## Keterampilan per agen vs bersama +Direktori native `$CODEX_HOME/skills` milik Codex CLI bukan salah satu root skill OpenClaw ini. Dalam mode harness Codex, peluncuran app-server lokal menggunakan home Codex terisolasi per agen, sehingga skill Codex CLI pribadi tidak dimuat secara implisit. Gunakan `openclaw migrate codex --dry-run` untuk menginventarisasinya dan `openclaw migrate codex` untuk memilih direktori skill dengan prompt kotak centang interaktif sebelum menyalinnya ke workspace agen OpenClaw saat ini. Untuk proses non-interaktif, ulangi `--skill ` untuk skill persis yang akan disalin. -Dalam penyiapan **multi-agen**, setiap agen memiliki ruang kerjanya sendiri: +## Skill per agen vs bersama -| Cakupan | Path | Terlihat oleh | +Dalam setup **multi-agen**, setiap agen memiliki workspace sendiri: + +| Cakupan | Jalur | Terlihat oleh | | -------------------- | ------------------------------------------- | ----------------------------- | | Per agen | `/skills` | Hanya agen tersebut | -| Agen proyek | `/.agents/skills` | Hanya agen ruang kerja itu | +| Agen proyek | `/.agents/skills` | Hanya agen workspace tersebut | | Agen pribadi | `~/.agents/skills` | Semua agen di mesin itu | -| Bersama terkelola/lokal | `~/.openclaw/skills` | Semua agen di mesin itu | -| Direktori tambahan bersama | `skills.load.extraDirs` (presedensi terendah) | Semua agen di mesin itu | +| Terkelola/lokal bersama | `~/.openclaw/skills` | Semua agen di mesin itu | +| Direktori ekstra bersama | `skills.load.extraDirs` (prioritas terendah) | Semua agen di mesin itu | -Nama yang sama di beberapa tempat → sumber tertinggi yang menang. Ruang kerja mengalahkan agen proyek, mengalahkan agen pribadi, mengalahkan terkelola/lokal, mengalahkan bawaan, mengalahkan direktori tambahan. +Nama yang sama di beberapa tempat → sumber tertinggi yang menang. Workspace mengalahkan agen proyek, mengalahkan agen pribadi, mengalahkan terkelola/lokal, mengalahkan bawaan, mengalahkan direktori ekstra. -## Daftar izin keterampilan agen +## Daftar izin skill agen -**Lokasi** keterampilan dan **visibilitas** keterampilan adalah kontrol yang terpisah. Lokasi/presedensi menentukan salinan mana dari keterampilan bernama sama yang menang; daftar izin agen menentukan keterampilan mana yang benar-benar dapat digunakan agen. +**Lokasi** skill dan **visibilitas** skill adalah kontrol yang terpisah. Lokasi/prioritas menentukan salinan mana dari skill bernama sama yang menang; daftar izin agen menentukan skill mana yang benar-benar dapat digunakan agen. ```json5 { @@ -67,55 +69,54 @@ Nama yang sama di beberapa tempat → sumber tertinggi yang menang. Ruang kerja - - Hilangkan `agents.defaults.skills` agar keterampilan tidak dibatasi secara default. + - Hilangkan `agents.defaults.skills` agar skill tidak dibatasi secara default. - Hilangkan `agents.list[].skills` untuk mewarisi `agents.defaults.skills`. - - Tetapkan `agents.list[].skills: []` agar tidak ada keterampilan. - - Daftar `agents.list[].skills` yang tidak kosong adalah set **final** untuk agen tersebut — daftar ini tidak digabungkan dengan default. - - Daftar izin efektif berlaku di seluruh pembuatan prompt, penemuan perintah slash keterampilan, sinkronisasi sandbox, dan snapshot keterampilan. - + - Tetapkan `agents.list[].skills: []` agar tidak ada skill. + - Daftar `agents.list[].skills` yang tidak kosong adalah set **final** untuk agen tersebut — daftar itu tidak digabungkan dengan default. + - Daftar izin efektif berlaku di seluruh pembuatan prompt, penemuan perintah slash skill, sinkronisasi sandbox, dan snapshot skill. -## Plugin dan keterampilan +## Plugin dan skill -Plugin dapat mengirimkan keterampilannya sendiri dengan mencantumkan direktori `skills` di `openclaw.plugin.json` (path relatif terhadap root Plugin). Keterampilan Plugin dimuat saat Plugin diaktifkan. Ini adalah tempat yang tepat untuk panduan operasi khusus alat yang terlalu panjang untuk deskripsi alat tetapi harus tersedia kapan pun Plugin diinstal — misalnya, Plugin browser mengirimkan keterampilan `browser-automation` untuk kontrol browser multi-langkah. +Plugin dapat mengirim skill mereka sendiri dengan mencantumkan direktori `skills` di `openclaw.plugin.json` (jalur relatif terhadap root plugin). Skill plugin dimuat saat plugin diaktifkan. Ini adalah tempat yang tepat untuk panduan operasi khusus alat yang terlalu panjang untuk deskripsi alat tetapi harus tersedia kapan pun plugin terinstal — misalnya, plugin browser mengirim skill `browser-automation` untuk kontrol browser multi-langkah. -Direktori keterampilan Plugin digabungkan ke path berpresedensi rendah yang sama seperti `skills.load.extraDirs`, jadi keterampilan bawaan, terkelola, agen, atau ruang kerja dengan nama sama akan menimpanya. Anda dapat membatasinya melalui `metadata.openclaw.requires.config` pada entri konfigurasi Plugin. +Direktori skill plugin digabungkan ke jalur berprioritas rendah yang sama seperti `skills.load.extraDirs`, sehingga skill bawaan, terkelola, agen, atau workspace dengan nama yang sama akan menimpanya. Anda dapat membatasinya melalui `metadata.openclaw.requires.config` pada entri konfigurasi plugin. -Lihat [Plugin](/id/tools/plugin) untuk penemuan/konfigurasi dan [Alat](/id/tools) untuk permukaan alat yang diajarkan oleh keterampilan tersebut. +Lihat [Plugin](/id/tools/plugin) untuk penemuan/konfigurasi dan [Alat](/id/tools) untuk permukaan alat yang diajarkan skill tersebut. -## Lokakarya Keterampilan +## Skill Workshop -Plugin **Lokakarya Keterampilan** yang opsional dan eksperimental dapat membuat atau memperbarui keterampilan ruang kerja dari prosedur pakai ulang yang diamati selama kerja agen. Plugin ini dinonaktifkan secara default dan harus diaktifkan secara eksplisit melalui `plugins.entries.skill-workshop`. +Plugin eksperimental opsional **Skill Workshop** dapat membuat atau memperbarui skill workspace dari prosedur pakai ulang yang diamati selama pekerjaan agen. Plugin ini dinonaktifkan secara default dan harus diaktifkan secara eksplisit melalui `plugins.entries.skill-workshop`. -Lokakarya Keterampilan hanya menulis ke `/skills`, memindai konten yang dihasilkan, mendukung persetujuan tertunda atau penulisan aman otomatis, mengarantina proposal yang tidak aman, dan menyegarkan snapshot keterampilan setelah penulisan berhasil sehingga keterampilan baru tersedia tanpa memulai ulang Gateway. +Skill Workshop hanya menulis ke `/skills`, memindai konten yang dihasilkan, mendukung persetujuan tertunda atau penulisan aman otomatis, mengarantina proposal yang tidak aman, dan menyegarkan snapshot skill setelah penulisan berhasil sehingga skill baru tersedia tanpa restart Gateway. -Gunakan untuk koreksi seperti _"lain kali, verifikasi atribusi GIF"_ atau alur kerja yang diperoleh dengan susah payah seperti daftar periksa QA media. Mulailah dengan persetujuan tertunda; gunakan penulisan otomatis hanya di ruang kerja tepercaya setelah meninjau proposalnya. Panduan lengkap: [Plugin Lokakarya Keterampilan](/id/plugins/skill-workshop). +Gunakan untuk koreksi seperti _"lain kali, verifikasi atribusi GIF"_ atau alur kerja yang diperoleh dengan susah payah seperti daftar periksa QA media. Mulailah dengan persetujuan tertunda; gunakan penulisan otomatis hanya di workspace tepercaya setelah meninjau proposalnya. Panduan lengkap: [Plugin Skill Workshop](/id/plugins/skill-workshop). -## ClawHub (instal dan sinkronkan) +## ClawHub (instal dan sinkronisasi) -[ClawHub](https://clawhub.ai) adalah registri keterampilan publik untuk OpenClaw. Gunakan perintah native `openclaw skills` untuk menemukan/menginstal/memperbarui, atau CLI `clawhub` terpisah untuk alur kerja publikasi/sinkronisasi. Panduan lengkap: [ClawHub](/id/tools/clawhub). +[ClawHub](https://clawhub.ai) adalah registri skill publik untuk OpenClaw. Gunakan perintah native `openclaw skills` untuk menemukan/menginstal/memperbarui, atau CLI `clawhub` terpisah untuk alur kerja publikasi/sinkronisasi. Panduan lengkap: [ClawHub](/id/tools/clawhub). | Tindakan | Perintah | -| --------------------------------- | ------------------------------------- | -| Instal keterampilan ke ruang kerja | `openclaw skills install ` | -| Perbarui semua keterampilan terinstal | `openclaw skills update --all` | -| Sinkronkan (pindai + publikasikan pembaruan) | `clawhub sync --all` | +| --------------------------------- | -------------------------------------- | +| Instal skill ke workspace | `openclaw skills install ` | +| Perbarui semua skill terinstal | `openclaw skills update --all` | +| Sinkronisasi (pindai + publikasikan pembaruan) | `clawhub sync --all` | -`openclaw skills install` native menginstal ke direktori `skills/` ruang kerja aktif. CLI `clawhub` terpisah juga menginstal ke `./skills` di bawah direktori kerja Anda saat ini (atau fallback ke ruang kerja OpenClaw yang dikonfigurasi). OpenClaw mengambilnya sebagai `/skills` pada sesi berikutnya. -Root keterampilan yang dikonfigurasi juga mendukung satu level pengelompokan, seperti `skills///SKILL.md`, sehingga keterampilan pihak ketiga yang terkait dapat disimpan di bawah folder bersama tanpa pemindaian rekursif yang luas. +`openclaw skills install` native menginstal ke direktori `skills/` workspace aktif. CLI `clawhub` terpisah juga menginstal ke `./skills` di bawah direktori kerja Anda saat ini (atau fallback ke workspace OpenClaw yang dikonfigurasi). OpenClaw mengambilnya sebagai `/skills` pada sesi berikutnya. +Root skill yang dikonfigurasi juga mendukung satu tingkat pengelompokan, seperti `skills///SKILL.md`, sehingga skill pihak ketiga terkait dapat disimpan di bawah folder bersama tanpa pemindaian rekursif yang luas. -Halaman keterampilan ClawHub menampilkan status pemindaian keamanan terbaru sebelum instalasi, dengan halaman detail pemindai untuk VirusTotal, ClawScan, dan analisis statis. `openclaw skills install ` tetap hanya sebagai jalur instalasi; penerbit memulihkan positif palsu melalui dasbor ClawHub atau `clawhub skill rescan `. +Halaman skill ClawHub menampilkan status pemindaian keamanan terbaru sebelum instalasi, dengan halaman detail pemindai untuk VirusTotal, ClawScan, dan analisis statis. `openclaw skills install ` tetap hanya jalur instalasi; penerbit memulihkan positif palsu melalui dasbor ClawHub atau `clawhub skill rescan `. ## Keamanan -Perlakukan keterampilan pihak ketiga sebagai **kode tidak tepercaya**. Baca sebelum mengaktifkannya. Utamakan eksekusi bersandbox untuk input tidak tepercaya dan alat berisiko. Lihat [Sandboxing](/id/gateway/sandboxing) untuk kontrol sisi agen. +Perlakukan skill pihak ketiga sebagai **kode tidak tepercaya**. Baca sebelum mengaktifkannya. Pilih proses bersandbox untuk input tidak tepercaya dan alat berisiko. Lihat [Sandboxing](/id/gateway/sandboxing) untuk kontrol sisi agen. -- Penemuan keterampilan ruang kerja dan direktori tambahan hanya menerima root keterampilan dan file `SKILL.md` yang realpath terselesaikannya tetap berada di dalam root yang dikonfigurasi. -- Instalasi dependensi keterampilan berbasis Gateway (`skills.install`, onboarding, dan UI pengaturan Skills) menjalankan pemindai kode berbahaya bawaan sebelum mengeksekusi metadata penginstal. Temuan `critical` memblokir secara default kecuali pemanggil secara eksplisit menetapkan override berbahaya; temuan mencurigakan tetap hanya memberi peringatan. -- `openclaw skills install ` berbeda — perintah ini mengunduh folder keterampilan ClawHub ke ruang kerja dan tidak menggunakan jalur metadata penginstal di atas. +- Penemuan skill workspace dan direktori ekstra hanya menerima root skill dan file `SKILL.md` yang realpath terselesaikannya tetap berada di dalam root yang dikonfigurasi. +- Instalasi dependensi skill yang didukung Gateway (`skills.install`, onboarding, dan UI pengaturan Skills) menjalankan pemindai kode berbahaya bawaan sebelum mengeksekusi metadata installer. Temuan `critical` memblokir secara default kecuali pemanggil secara eksplisit menetapkan override berbahaya; temuan mencurigakan tetap hanya memperingatkan. +- `openclaw skills install ` berbeda — perintah itu mengunduh folder skill ClawHub ke workspace dan tidak menggunakan jalur metadata installer di atas. - `skills.entries.*.env` dan `skills.entries.*.apiKey` menyuntikkan rahasia ke proses **host** untuk giliran agen tersebut (bukan sandbox). Jauhkan rahasia dari prompt dan log. Untuk model ancaman dan daftar periksa yang lebih luas, lihat [Keamanan](/id/gateway/security). @@ -131,7 +132,7 @@ description: Generate or edit images via a provider-backed image workflow --- ``` -OpenClaw mengikuti spesifikasi AgentSkills untuk tata letak/tujuan. Parser yang digunakan oleh agen tertanam hanya mendukung kunci frontmatter **satu baris**; `metadata` harus berupa **objek JSON satu baris**. Gunakan `{baseDir}` dalam instruksi untuk merujuk ke path folder keterampilan. +OpenClaw mengikuti spesifikasi AgentSkills untuk tata letak/niat. Parser yang digunakan oleh agen tertanam hanya mendukung kunci frontmatter **satu baris**; `metadata` harus berupa **objek JSON satu baris**. Gunakan `{baseDir}` dalam instruksi untuk merujuk jalur folder skill. ### Kunci frontmatter opsional @@ -139,24 +140,24 @@ OpenClaw mengikuti spesifikasi AgentSkills untuk tata letak/tujuan. Parser yang URL yang ditampilkan sebagai "Situs web" di UI Skills macOS. Juga didukung melalui `metadata.openclaw.homepage`. - Saat `true`, keterampilan ditampilkan sebagai perintah slash pengguna. + Saat `true`, skill ditampilkan sebagai perintah slash pengguna. - Saat `true`, keterampilan dikecualikan dari prompt model (tetap tersedia melalui pemanggilan pengguna). + Saat `true`, skill dikecualikan dari prompt model (tetap tersedia melalui pemanggilan pengguna). Saat diatur ke `tool`, perintah slash melewati model dan dikirim langsung ke alat. - Nama alat yang akan dipanggil saat `command-dispatch: tool` diatur. + Nama alat yang akan dipanggil saat `command-dispatch: tool` ditetapkan. - Untuk pengiriman alat, meneruskan string argumen mentah ke alat (tanpa parsing inti). Alat dipanggil dengan `{ command: "", commandName: "", skillName: "" }`. + Untuk pengiriman alat, meneruskan string arg mentah ke alat (tanpa parsing core). Alat dipanggil dengan `{ command: "", commandName: "", skillName: "" }`. ## Pembatasan (filter saat pemuatan) -OpenClaw memfilter keterampilan saat pemuatan menggunakan `metadata` (JSON satu baris): +OpenClaw memfilter skill saat pemuatan menggunakan `metadata` (JSON satu baris): ```markdown --- @@ -173,10 +174,10 @@ metadata: --- ``` -Bidang di bawah `metadata.openclaw`: +Kolom di bawah `metadata.openclaw`: - Saat `true`, selalu sertakan keterampilan (lewati pembatas lain). + Saat `true`, selalu sertakan skill (lewati gate lain). Emoji opsional yang digunakan oleh UI Skills macOS. @@ -185,7 +186,7 @@ Bidang di bawah `metadata.openclaw`: URL opsional yang ditampilkan sebagai "Situs web" di UI Skills macOS. - Daftar platform opsional. Jika diatur, keterampilan hanya memenuhi syarat pada OS tersebut. + Daftar platform opsional. Jika ditetapkan, skill hanya memenuhi syarat pada OS tersebut. Masing-masing harus ada di `PATH`. @@ -194,31 +195,31 @@ Bidang di bawah `metadata.openclaw`: Setidaknya satu harus ada di `PATH`. - Variabel lingkungan harus ada atau disediakan dalam konfigurasi. + Variabel env harus ada atau disediakan dalam config. - Daftar path `openclaw.json` yang harus bernilai truthy. + Daftar jalur `openclaw.json` yang harus bernilai truthy. - Nama variabel lingkungan yang terkait dengan `skills.entries..apiKey`. + Nama variabel env yang terkait dengan `skills.entries..apiKey`. - Spesifikasi penginstal opsional yang digunakan oleh UI Skills macOS (brew/node/go/uv/download). + Spesifikasi installer opsional yang digunakan oleh UI Skills macOS (brew/node/go/uv/download). -Jika tidak ada `metadata.openclaw`, keterampilan selalu memenuhi syarat (kecuali dinonaktifkan dalam konfigurasi atau diblokir oleh `skills.allowBundled` untuk keterampilan bawaan). +Jika tidak ada `metadata.openclaw`, skill selalu memenuhi syarat (kecuali dinonaktifkan dalam config atau diblokir oleh `skills.allowBundled` untuk skill bawaan). -Blok `metadata.clawdbot` lama masih diterima saat `metadata.openclaw` tidak ada, sehingga keterampilan lama yang terinstal tetap mempertahankan pembatas dependensi dan petunjuk penginstalnya. Keterampilan baru dan yang diperbarui harus menggunakan `metadata.openclaw`. +Blok lama `metadata.clawdbot` masih diterima saat `metadata.openclaw` tidak ada, sehingga skill lama yang terinstal tetap mempertahankan gate dependensi dan petunjuk installernya. Skill baru dan yang diperbarui harus menggunakan `metadata.openclaw`. ### Catatan sandboxing -- `requires.bins` diperiksa pada **host** saat pemuatan keterampilan. -- Jika agen disandbox, biner juga harus ada **di dalam kontainer**. Instal melalui `agents.defaults.sandbox.docker.setupCommand` (atau image kustom). `setupCommand` berjalan sekali setelah kontainer dibuat. Instalasi paket juga memerlukan egress jaringan, FS root yang dapat ditulis, dan pengguna root di sandbox. -- Contoh: keterampilan `summarize` (`skills/summarize/SKILL.md`) memerlukan CLI `summarize` di kontainer sandbox untuk berjalan di sana. +- `requires.bins` diperiksa pada **host** saat pemuatan skill. +- Jika agen disandbox, biner juga harus ada **di dalam container**. Instal melalui `agents.defaults.sandbox.docker.setupCommand` (atau image kustom). `setupCommand` berjalan sekali setelah container dibuat. Instalasi paket juga memerlukan egress jaringan, root FS yang dapat ditulis, dan pengguna root di sandbox. +- Contoh: skill `summarize` (`skills/summarize/SKILL.md`) memerlukan CLI `summarize` di container sandbox agar dapat berjalan di sana. -### Spesifikasi penginstal +### Spesifikasi installer ```markdown --- @@ -246,25 +247,25 @@ metadata: ``` - - - Jika beberapa penginstal dicantumkan, Gateway memilih satu opsi yang diutamakan (brew jika tersedia, jika tidak node). + + - Jika beberapa penginstal dicantumkan, gateway memilih satu opsi pilihan (brew jika tersedia, jika tidak node). - Jika semua penginstal adalah `download`, OpenClaw mencantumkan setiap entri agar Anda dapat melihat artefak yang tersedia. - Spesifikasi penginstal dapat menyertakan `os: ["darwin"|"linux"|"win32"]` untuk memfilter opsi berdasarkan platform. - - Instalasi Node mematuhi `skills.install.nodeManager` di `openclaw.json` (default: npm; opsi: npm/pnpm/yarn/bun). Ini hanya memengaruhi instalasi skill; runtime Gateway tetap sebaiknya Node — Bun tidak disarankan untuk WhatsApp/Telegram. - - Pemilihan penginstal yang didukung Gateway digerakkan oleh preferensi: ketika spesifikasi instalasi mencampur beberapa jenis, OpenClaw mengutamakan Homebrew saat `skills.install.preferBrew` diaktifkan dan `brew` ada, lalu `uv`, lalu manajer node yang dikonfigurasi, lalu fallback lain seperti `go` atau `download`. - - Jika setiap spesifikasi instalasi adalah `download`, OpenClaw menampilkan semua opsi unduhan alih-alih meringkasnya menjadi satu penginstal yang diutamakan. + - Instalasi Node mengikuti `skills.install.nodeManager` di `openclaw.json` (default: npm; opsi: npm/pnpm/yarn/bun). Ini hanya memengaruhi instalasi skill; runtime Gateway tetap harus berupa Node — Bun tidak direkomendasikan untuk WhatsApp/Telegram. + - Pemilihan penginstal yang didukung Gateway digerakkan oleh preferensi: ketika spesifikasi instalasi mencampur beberapa jenis, OpenClaw lebih memilih Homebrew saat `skills.install.preferBrew` diaktifkan dan `brew` ada, lalu `uv`, lalu manajer node yang dikonfigurasi, lalu fallback lain seperti `go` atau `download`. + - Jika setiap spesifikasi instalasi adalah `download`, OpenClaw menampilkan semua opsi unduhan alih-alih meringkasnya menjadi satu penginstal pilihan. - - - **Instalasi Go:** jika `go` tidak ada dan `brew` tersedia, gateway menginstal Go melalui Homebrew terlebih dahulu dan mengatur `GOBIN` ke `bin` Homebrew jika memungkinkan. + + - **Instalasi Go:** jika `go` tidak ada dan `brew` tersedia, gateway menginstal Go melalui Homebrew terlebih dahulu dan mengatur `GOBIN` ke `bin` milik Homebrew jika memungkinkan. - **Instalasi unduhan:** `url` (wajib), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (default: otomatis saat arsip terdeteksi), `stripComponents`, `targetDir` (default: `~/.openclaw/tools/`). -## Penimpaan konfigurasi +## Override konfigurasi -Skill bawaan dan terkelola dapat diaktifkan/nonaktifkan dan diberi nilai env +Skill bawaan dan terkelola dapat diaktifkan/nonaktifkan serta diberi nilai env di bawah `skills.entries` dalam `~/.openclaw/openclaw.json`: ```json5 @@ -292,35 +293,35 @@ di bawah `skills.entries` dalam `~/.openclaw/openclaw.json`: `false` menonaktifkan skill meskipun skill tersebut dibundel atau diinstal. Skill `coding-agent` bawaan bersifat opt-in: atur - `skills.entries.coding-agent.enabled: true` sebelum menampilkannya kepada agen, - lalu pastikan salah satu dari `claude`, `codex`, `opencode`, atau `pi` terinstal dan - terautentikasi untuk CLI-nya sendiri. + `skills.entries.coding-agent.enabled: true` sebelum menampilkannya ke agen, + lalu pastikan salah satu dari `claude`, `codex`, `opencode`, atau `pi` telah diinstal dan + diautentikasi untuk CLI-nya sendiri. - Kemudahan untuk skill yang mendeklarasikan `metadata.openclaw.primaryEnv`. Mendukung teks polos atau SecretRef. + Kemudahan untuk skill yang mendeklarasikan `metadata.openclaw.primaryEnv`. Mendukung plaintext atau SecretRef. - Diinjeksikan hanya jika variabel belum diatur dalam proses. + Diinjeksi hanya jika variabel belum diatur dalam proses. - Wadah opsional untuk bidang kustom per skill. Kunci kustom harus berada di sini. + Wadah opsional untuk field per-skill kustom. Key kustom harus berada di sini. Allowlist opsional hanya untuk skill **bawaan**. Jika diatur, hanya skill bawaan dalam daftar yang memenuhi syarat (skill terkelola/workspace tidak terpengaruh). -Jika nama skill berisi tanda hubung, kutip kuncinya (JSON5 mengizinkan kunci -yang dikutip). Kunci konfigurasi secara default cocok dengan **nama skill** — jika sebuah skill -mendefinisikan `metadata.openclaw.skillKey`, gunakan kunci tersebut di bawah `skills.entries`. +Jika nama skill berisi tanda hubung, beri tanda kutip pada key (JSON5 mengizinkan +key yang dikutip). Key konfigurasi cocok dengan **nama skill** secara default — jika sebuah skill +mendefinisikan `metadata.openclaw.skillKey`, gunakan key tersebut di bawah `skills.entries`. -Untuk pembuatan/penyuntingan gambar stok di dalam OpenClaw, gunakan tool inti +Untuk pembuatan/pengeditan gambar stok di dalam OpenClaw, gunakan tool inti `image_generate` dengan `agents.defaults.imageGenerationModel` alih-alih -skill bawaan. Contoh skill di sini ditujukan untuk alur kerja kustom atau pihak ketiga. +skill bawaan. Contoh skill di sini ditujukan untuk workflow kustom atau pihak ketiga. Untuk analisis gambar native, gunakan tool `image` dengan `agents.defaults.imageModel`. Jika Anda memilih `openai/*`, `google/*`, -`fal/*`, atau model gambar khusus penyedia lain, tambahkan juga -auth/kunci API penyedia tersebut. +`fal/*`, atau model gambar khusus provider lainnya, tambahkan juga +auth/key API provider tersebut. ## Injeksi lingkungan @@ -329,33 +330,33 @@ Saat sebuah run agen dimulai, OpenClaw: 1. Membaca metadata skill. 2. Menerapkan `skills.entries..env` dan `skills.entries..apiKey` ke `process.env`. -3. Membangun prompt sistem dengan skill yang **memenuhi syarat**. +3. Membuat system prompt dengan skill yang **memenuhi syarat**. 4. Memulihkan lingkungan asli setelah run berakhir. -Injeksi lingkungan **bercakupan pada run agen**, bukan lingkungan shell +Injeksi lingkungan **tercakup pada run agen**, bukan lingkungan shell global. -Untuk backend `claude-cli` bawaan, OpenClaw juga mewujudkan snapshot +Untuk backend `claude-cli` bawaan, OpenClaw juga merealisasikan snapshot memenuhi syarat yang sama sebagai Plugin Claude Code sementara dan meneruskannya dengan `--plugin-dir`. Claude Code kemudian dapat menggunakan resolver skill native-nya sementara -OpenClaw tetap mengelola prioritas, allowlist per agen, gating, dan -injeksi env/kunci API `skills.entries.*`. Backend CLI lain hanya menggunakan +OpenClaw tetap mengelola presedensi, allowlist per agen, gating, dan +injeksi env/key API `skills.entries.*`. Backend CLI lain hanya menggunakan katalog prompt. -## Snapshot dan refresh +## Snapshot dan penyegaran -OpenClaw membuat snapshot skill yang memenuhi syarat **saat sesi dimulai** dan -menggunakan kembali daftar itu untuk giliran berikutnya dalam sesi yang sama. Perubahan pada -skill atau konfigurasi mulai berlaku pada sesi baru berikutnya. +OpenClaw mengambil snapshot skill yang memenuhi syarat **saat sesi dimulai** dan +menggunakan kembali daftar tersebut untuk giliran berikutnya dalam sesi yang sama. Perubahan pada +skill atau konfigurasi berlaku pada sesi baru berikutnya. -Skills dapat di-refresh di tengah sesi dalam dua kasus: +Skills dapat disegarkan di tengah sesi dalam dua kasus: - Watcher skills diaktifkan. - Node jarak jauh baru yang memenuhi syarat muncul. -Anggap ini sebagai **hot reload**: daftar yang di-refresh digunakan pada +Anggap ini sebagai **hot reload**: daftar yang disegarkan digunakan pada giliran agen berikutnya. Jika allowlist skill agen efektif berubah untuk -sesi tersebut, OpenClaw me-refresh snapshot agar skill yang terlihat tetap selaras +sesi tersebut, OpenClaw menyegarkan snapshot agar skill yang terlihat tetap selaras dengan agen saat ini. ### Watcher Skills @@ -378,20 +379,20 @@ saat file `SKILL.md` berubah. Konfigurasikan di bawah `skills.load`: Jika Gateway berjalan di Linux tetapi sebuah **node macOS** terhubung dengan `system.run` diizinkan (keamanan persetujuan Exec tidak diatur ke `deny`), -OpenClaw dapat memperlakukan skill khusus macOS sebagai memenuhi syarat ketika biner yang diperlukan -ada pada node tersebut. Agen harus menjalankan skill tersebut +OpenClaw dapat memperlakukan skill khusus macOS sebagai memenuhi syarat ketika +binary yang diperlukan ada pada node tersebut. Agen harus menjalankan skill tersebut melalui tool `exec` dengan `host=node`. Ini bergantung pada node yang melaporkan dukungan perintahnya dan pada probe bin melalui `system.which` atau `system.run`. Node offline **tidak** membuat -skill khusus jarak jauh terlihat. Jika node yang terhubung berhenti menjawab probe bin, -OpenClaw menghapus kecocokan bin yang di-cache sehingga agen tidak lagi melihat +skill khusus jarak jauh terlihat. Jika node yang terhubung berhenti menjawab probe +bin, OpenClaw menghapus kecocokan bin yang di-cache agar agen tidak lagi melihat skill yang saat ini tidak dapat dijalankan di sana. ## Dampak token -Saat skill memenuhi syarat, OpenClaw menginjeksikan daftar XML ringkas berisi skill yang tersedia -ke dalam prompt sistem (melalui `formatSkillsForPrompt` di +Ketika skill memenuhi syarat, OpenClaw menginjeksi daftar XML ringkas dari skill yang tersedia +ke dalam system prompt (melalui `formatSkillsForPrompt` di `pi-coding-agent`). Biayanya deterministik: - **Overhead dasar** (hanya saat ≥1 skill): 195 karakter. @@ -403,18 +404,18 @@ Rumus (karakter): total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped)) ``` -Escaping XML memperluas `& < > " '` menjadi entitas (`&`, `<`, dll.), +Escape XML memperluas `& < > " '` menjadi entitas (`&`, `<`, dll.), sehingga menambah panjang. Jumlah token bervariasi menurut tokenizer model. Perkiraan kasar gaya OpenAI adalah ~4 karakter/token, jadi **97 karakter ≈ 24 token** per -skill ditambah panjang bidang Anda yang sebenarnya. +skill ditambah panjang field aktual Anda. ## Siklus hidup skill terkelola -OpenClaw mengirimkan set dasar skill sebagai **skill bawaan** bersama -instalasi (paket npm atau OpenClaw.app). `~/.openclaw/skills` ada untuk -penimpaan lokal — misalnya, menyematkan atau menambal skill tanpa -mengubah salinan bawaan. Skill workspace dimiliki pengguna dan menimpa -keduanya saat terjadi konflik nama. +OpenClaw menyertakan satu set dasar skill sebagai **skill bawaan** bersama +instalasi (paket npm atau OpenClaw.app). `~/.openclaw/skills` tersedia untuk +override lokal — misalnya, melakukan pin atau patch pada skill tanpa +mengubah salinan bawaan. Skill workspace dimiliki pengguna dan mengoverride +keduanya saat ada konflik nama. ## Mencari lebih banyak skill? @@ -425,7 +426,7 @@ Jelajahi [https://clawhub.ai](https://clawhub.ai). Skema konfigurasi lengkap: - [ClawHub](/id/tools/clawhub) — registri skill publik - [Membuat skill](/id/tools/creating-skills) — membangun skill kustom -- [Plugin](/id/tools/plugin) — ikhtisar sistem plugin -- [Plugin Skill Workshop](/id/plugins/skill-workshop) — menghasilkan skill dari pekerjaan agen +- [Plugins](/id/tools/plugin) — ikhtisar sistem plugin +- [Plugin Skill Workshop](/id/plugins/skill-workshop) — hasilkan skill dari pekerjaan agen - [Konfigurasi Skills](/id/tools/skills-config) — referensi konfigurasi skill - [Perintah slash](/id/tools/slash-commands) — semua perintah slash yang tersedia