OpenClaw membaca config opsional dariDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
~/.openclaw/openclaw.json.
Path config aktif harus berupa file biasa. Tata letak openclaw.json
berupa symlink tidak didukung untuk penulisan milik OpenClaw; penulisan atomik dapat mengganti
path tersebut alih-alih mempertahankan symlink. Jika Anda menyimpan config di luar
direktori state default, arahkan OPENCLAW_CONFIG_PATH langsung ke file sebenarnya.
Jika file tidak ada, OpenClaw menggunakan default yang aman. Alasan umum untuk menambahkan config:
- Menghubungkan channel dan mengontrol siapa yang dapat mengirim pesan ke bot
- Menetapkan model, tool, sandboxing, atau otomasi (cron, hook)
- Menyesuaikan sesi, media, jaringan, atau UI
config.schema.lookup untuk dokumentasi tingkat field yang tepat
sebelum mengedit config. Gunakan halaman ini untuk panduan berorientasi tugas dan
Referensi konfigurasi untuk peta field dan default
yang lebih luas.
Config minimal
Mengedit config
- Wizard interaktif
- CLI (satu baris)
- UI Kontrol
- Edit langsung
Validasi ketat
openclaw config schema mencetak JSON Schema kanonis yang digunakan oleh UI Kontrol
dan validasi. config.schema.lookup mengambil satu node dengan cakupan path beserta
ringkasan child untuk tooling telusur detail. Metadata dokumentasi field title/description
diteruskan melalui objek bertingkat, wildcard (*), item array ([]), dan cabang anyOf/
oneOf/allOf. Skema plugin dan channel runtime digabungkan saat
registri manifest dimuat.
Saat validasi gagal:
- Gateway tidak melakukan boot
- Hanya perintah diagnostik yang berfungsi (
openclaw doctor,openclaw logs,openclaw health,openclaw status) - Jalankan
openclaw doctoruntuk melihat masalah yang tepat - Jalankan
openclaw doctor --fix(atau--yes) untuk menerapkan perbaikan
openclaw.json
gagal validasi (termasuk validasi lokal plugin), startup Gateway gagal atau
reload dilewati dan runtime saat ini mempertahankan config terakhir yang diterima.
Jalankan openclaw doctor --fix (atau --yes) untuk memperbaiki config yang diberi prefiks/tertindih atau
memulihkan salinan terakhir yang diketahui baik. Promosi ke terakhir yang diketahui baik dilewati saat
kandidat berisi placeholder secret yang disensor seperti ***.
Tugas umum
Menyiapkan channel (WhatsApp, Telegram, Discord, dll.)
Menyiapkan channel (WhatsApp, Telegram, Discord, dll.)
channels.<provider>. Lihat halaman channel khusus untuk langkah penyiapan:- WhatsApp -
channels.whatsapp - Telegram -
channels.telegram - Discord -
channels.discord - Feishu -
channels.feishu - Google Chat -
channels.googlechat - Microsoft Teams -
channels.msteams - Slack -
channels.slack - Signal -
channels.signal - iMessage -
channels.imessage - Mattermost -
channels.mattermost
Memilih dan mengonfigurasi model
Memilih dan mengonfigurasi model
agents.defaults.modelsmendefinisikan katalog model dan bertindak sebagai allowlist untuk/model; entriprovider/*memfilter/model,/models, dan pemilih model ke provider yang dipilih sambil tetap menggunakan penemuan model dinamis.- Gunakan
openclaw config set agents.defaults.models '<json>' --strict-json --mergeuntuk menambahkan entri allowlist tanpa menghapus model yang ada. Penggantian biasa yang akan menghapus entri ditolak kecuali Anda meneruskan--replace. - Referensi model menggunakan format
provider/model(mis.anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPxmengontrol downscaling gambar transcript/tool (default1200); nilai yang lebih rendah biasanya mengurangi penggunaan vision-token pada proses yang banyak memakai screenshot.- Lihat CLI Model untuk mengganti model dalam chat dan Failover Model untuk rotasi auth dan perilaku fallback.
- Untuk provider custom/self-hosted, lihat Provider custom di referensi.
Mengontrol siapa yang dapat mengirim pesan ke bot
Mengontrol siapa yang dapat mengirim pesan ke bot
dmPolicy:"pairing"(default): pengirim tidak dikenal mendapatkan kode pairing sekali pakai untuk disetujui"allowlist": hanya pengirim diallowFrom(atau penyimpanan izin yang sudah dipairing)"open": izinkan semua DM masuk (memerlukanallowFrom: ["*"])"disabled": abaikan semua DM
groupPolicy + groupAllowFrom atau allowlist khusus channel.Lihat referensi lengkap untuk detail per channel.Menyiapkan gating mention chat grup
Menyiapkan gating mention chat grup
- Mention metadata: @-mention native (tap-to-mention WhatsApp, @bot Telegram, dll.)
- Pola teks: pola regex aman di
mentionPatterns - Balasan terlihat:
messages.visibleRepliesdapat mewajibkan pengiriman tool pesan secara global;messages.groupChat.visibleRepliesmenimpanya untuk grup/channel. - Lihat referensi lengkap untuk mode balasan terlihat, override per channel, dan mode chat mandiri.
Membatasi skills per agent
Membatasi skills per agent
agents.defaults.skills untuk baseline bersama, lalu override agent
tertentu dengan agents.list[].skills:- Hilangkan
agents.defaults.skillsuntuk skills yang tidak dibatasi secara default. - Hilangkan
agents.list[].skillsuntuk mewarisi default. - Tetapkan
agents.list[].skills: []untuk tanpa skills. - Lihat Skills, Config Skills, dan Referensi Konfigurasi.
Menyesuaikan pemantauan kesehatan channel gateway
Menyesuaikan pemantauan kesehatan channel gateway
- Tetapkan
gateway.channelHealthCheckMinutes: 0untuk menonaktifkan restart health-monitor secara global. channelStaleEventThresholdMinutesharus lebih besar dari atau sama dengan interval pemeriksaan.- Gunakan
channels.<provider>.healthMonitor.enabledatauchannels.<provider>.accounts.<id>.healthMonitor.enableduntuk menonaktifkan auto-restart untuk satu channel atau akun tanpa menonaktifkan monitor global. - Lihat Pemeriksaan Kesehatan untuk debugging operasional dan referensi lengkap untuk semua field.
Menyesuaikan timeout handshake WebSocket gateway
Menyesuaikan timeout handshake WebSocket gateway
- Default adalah
15000milidetik. OPENCLAW_HANDSHAKE_TIMEOUT_MStetap memiliki prioritas untuk override layanan atau shell sekali pakai.- Utamakan memperbaiki stall startup/event-loop terlebih dahulu; knob ini untuk host yang sehat tetapi lambat saat warmup.
Mengonfigurasi sesi dan reset
Mengonfigurasi sesi dan reset
dmScope:main(bersama) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: default global untuk perutean sesi yang terikat utas (Discord mendukung/focus,/unfocus,/agents,/session idle, dan/session max-age).- Lihat Manajemen Sesi untuk cakupan, tautan identitas, dan kebijakan pengiriman.
- Lihat referensi lengkap untuk semua bidang.
Aktifkan sandboxing
Aktifkan sandboxing
scripts/sandbox-setup.sh, atau dari instalasi npm lihat perintah inline docker build di Sandboxing § Image dan penyiapan.Lihat Sandboxing untuk panduan lengkap dan referensi lengkap untuk semua opsi.Aktifkan push berbasis relay untuk build iOS resmi
Aktifkan push berbasis relay untuk build iOS resmi
openclaw.json.Tetapkan ini dalam konfigurasi gateway:- Memungkinkan gateway mengirim
push.test, dorongan bangun, dan bangun ulang koneksi melalui relay eksternal. - Menggunakan izin pengiriman bercakupan pendaftaran yang diteruskan oleh aplikasi iOS yang dipasangkan. Gateway tidak memerlukan token relay untuk seluruh deployment.
- Mengikat setiap pendaftaran berbasis relay ke identitas gateway yang dipasangkan dengan aplikasi iOS, sehingga gateway lain tidak dapat menggunakan kembali pendaftaran yang tersimpan.
- Mempertahankan build iOS lokal/manual pada APNs langsung. Pengiriman berbasis relay hanya berlaku untuk build distribusi resmi yang mendaftar melalui relay.
- Harus cocok dengan URL dasar relay yang dibenamkan dalam build iOS resmi/TestFlight, sehingga lalu lintas pendaftaran dan pengiriman mencapai deployment relay yang sama.
- Instal build iOS resmi/TestFlight yang dikompilasi dengan URL dasar relay yang sama.
- Konfigurasikan
gateway.push.apns.relay.baseUrlpada gateway. - Pasangkan aplikasi iOS ke gateway dan biarkan sesi node serta operator tersambung.
- Aplikasi iOS mengambil identitas gateway, mendaftar ke relay menggunakan App Attest plus tanda terima aplikasi, lalu menerbitkan payload
push.apns.registerberbasis relay ke gateway yang dipasangkan. - Gateway menyimpan handle relay dan izin pengiriman, lalu menggunakannya untuk
push.test, dorongan bangun, dan bangun ulang koneksi.
- Jika Anda mengalihkan aplikasi iOS ke gateway berbeda, sambungkan ulang aplikasi agar dapat menerbitkan pendaftaran relay baru yang terikat ke gateway tersebut.
- Jika Anda mengirim build iOS baru yang mengarah ke deployment relay berbeda, aplikasi menyegarkan pendaftaran relay yang di-cache alih-alih menggunakan ulang asal relay lama.
OPENCLAW_APNS_RELAY_BASE_URLdanOPENCLAW_APNS_RELAY_TIMEOUT_MSmasih berfungsi sebagai override env sementara.OPENCLAW_APNS_RELAY_ALLOW_HTTP=truetetap menjadi jalan keluar pengembangan khusus loopback; jangan simpan URL relay HTTP dalam konfigurasi.
Siapkan heartbeat (check-in berkala)
Siapkan heartbeat (check-in berkala)
every: string durasi (30m,2h). Tetapkan0muntuk menonaktifkan.target:last|none|<channel-id>(misalnyadiscord,matrix,telegram, atauwhatsapp)directPolicy:allow(default) ataublockuntuk target heartbeat bergaya DM- Lihat Heartbeat untuk panduan lengkap.
Konfigurasikan tugas cron
Konfigurasikan tugas cron
sessionRetention: pangkas sesi eksekusi terisolasi yang selesai darisessions.json(default24h; tetapkanfalseuntuk menonaktifkan).runLog: pangkascron/runs/<jobId>.jsonlberdasarkan ukuran dan baris yang dipertahankan.- Lihat Tugas Cron untuk ringkasan fitur dan contoh CLI.
Siapkan webhook (hook)
Siapkan webhook (hook)
- Perlakukan semua konten payload hook/webhook sebagai input yang tidak tepercaya.
- Gunakan
hooks.tokenkhusus; jangan gunakan ulang token Gateway bersama. - Autentikasi hook hanya melalui header (
Authorization: Bearer ...ataux-openclaw-token); token query string ditolak. hooks.pathtidak boleh berupa/; pertahankan ingress webhook pada subpath khusus seperti/hooks.- Biarkan flag bypass konten tidak aman tetap nonaktif (
hooks.gmail.allowUnsafeExternalContent,hooks.mappings[].allowUnsafeExternalContent) kecuali saat melakukan debugging dengan cakupan ketat. - Jika Anda mengaktifkan
hooks.allowRequestSessionKey, tetapkan jugahooks.allowedSessionKeyPrefixesuntuk membatasi kunci sesi yang dipilih pemanggil. - Untuk agen yang digerakkan hook, utamakan tier model modern yang kuat dan kebijakan alat yang ketat (misalnya hanya perpesanan plus sandboxing jika memungkinkan).
Konfigurasikan perutean multi-agen
Konfigurasikan perutean multi-agen
Pisahkan konfigurasi menjadi beberapa file ($include)
Pisahkan konfigurasi menjadi beberapa file ($include)
$include untuk mengatur konfigurasi besar:- File tunggal: menggantikan objek yang memuatnya
- Array file: digabung secara mendalam sesuai urutan (yang belakangan menang)
- Kunci saudara: digabung setelah include (menimpa nilai yang di-include)
- Include bertingkat: didukung hingga kedalaman 10 level
- Path relatif: di-resolve relatif terhadap file yang meng-include
- Penulisan milik OpenClaw: saat penulisan hanya mengubah satu bagian level atas
yang didukung oleh include file tunggal seperti
plugins: { $include: "./plugins.json5" }, OpenClaw memperbarui file yang di-include tersebut dan membiarkanopenclaw.jsontetap utuh - Write-through yang tidak didukung: include root, array include, dan include dengan override saudara gagal tertutup untuk penulisan milik OpenClaw alih-alih meratakan konfigurasi
- Pengurungan: path
$includeharus di-resolve di bawah direktori yang memuatopenclaw.json. Untuk berbagi tree antar mesin atau pengguna, tetapkanOPENCLAW_INCLUDE_ROOTSke daftar path (:di POSIX,;di Windows) berisi direktori tambahan yang dapat dirujuk oleh include. Symlink di-resolve dan diperiksa ulang, sehingga path yang secara leksikal berada di dir konfigurasi tetapi target aslinya keluar dari setiap root yang diizinkan tetap ditolak. - Penanganan galat: galat yang jelas untuk file yang hilang, galat parse, dan include melingkar
Hot reload konfigurasi
Gateway memantau~/.openclaw/openclaw.json dan menerapkan perubahan secara otomatis - restart manual tidak diperlukan untuk sebagian besar pengaturan.
Edit file langsung diperlakukan sebagai tidak tepercaya sampai lolos validasi. Watcher menunggu
pergantian tulis-sementara/rename dari editor reda, membaca file final, dan menolak
edit eksternal yang tidak valid tanpa menulis ulang openclaw.json. Penulisan konfigurasi
milik OpenClaw menggunakan gerbang skema yang sama sebelum menulis; clobber destruktif seperti
menghapus gateway.mode atau mengecilkan file lebih dari setengahnya ditolak dan
disimpan sebagai .rejected.* untuk inspeksi.
Jika Anda melihat config reload skipped (invalid config) atau startup melaporkan Invalid config, periksa konfigurasi, jalankan openclaw config validate, lalu jalankan openclaw doctor --fix untuk perbaikan. Lihat Pemecahan masalah Gateway
untuk checklist.
Mode reload
| Mode | Perilaku |
|---|---|
hybrid (default) | Menerapkan perubahan aman secara hot dengan segera. Otomatis restart untuk perubahan kritis. |
hot | Hanya menerapkan perubahan aman secara hot. Mencatat peringatan saat restart diperlukan - Anda yang menanganinya. |
restart | Me-restart Gateway pada perubahan konfigurasi apa pun, aman atau tidak. |
off | Menonaktifkan pemantauan file. Perubahan berlaku pada restart manual berikutnya. |
Yang diterapkan secara hot vs yang memerlukan restart
Sebagian besar bidang diterapkan secara hot tanpa downtime. Dalam modehybrid, perubahan yang memerlukan restart ditangani secara otomatis.
| Kategori | Bidang | Perlu restart? |
|---|---|---|
| Channel | channels.*, web (WhatsApp) - semua channel bawaan dan plugin | Tidak |
| Agen & model | agent, agents, models, routing | Tidak |
| Otomasi | hooks, cron, agent.heartbeat | Tidak |
| Sesi & pesan | session, messages | Tidak |
| Alat & media | tools, browser, skills, mcp, audio, talk | Tidak |
| UI & lain-lain | ui, logging, identity, bindings | Tidak |
| Server Gateway | gateway.* (port, bind, auth, tailscale, TLS, HTTP) | Ya |
| Infrastruktur | discovery, plugins | Ya |
gateway.reload dan gateway.remote adalah pengecualian - mengubahnya tidak memicu restart.Perencanaan reload
Saat Anda mengedit file sumber yang dirujuk melalui$include, OpenClaw merencanakan
reload dari tata letak yang ditulis di sumber, bukan tampilan memori yang sudah diratakan.
Hal ini menjaga keputusan hot-reload (hot-apply vs restart) tetap dapat diprediksi meskipun
satu bagian tingkat atas berada di file terinclude miliknya sendiri seperti
plugins: { $include: "./plugins.json5" }. Perencanaan reload gagal secara tertutup jika
tata letak sumber ambigu.
Config RPC (pembaruan programatis)
Untuk tooling yang menulis konfigurasi melalui API Gateway, gunakan alur ini:config.schema.lookupuntuk memeriksa satu subtree (node skema dangkal + ringkasan anak)config.getuntuk mengambil snapshot saat ini plushashconfig.patchuntuk pembaruan parsial (JSON merge patch: objek digabung,nullmenghapus, array mengganti)config.applyhanya saat Anda bermaksud mengganti seluruh konfigurasiupdate.rununtuk self-update eksplisit plus restart; sertakancontinuationMessagesaat sesi pasca-restart harus menjalankan satu giliran lanjutanupdate.statusuntuk memeriksa sentinel restart pembaruan terbaru dan memverifikasi versi yang berjalan setelah restart
config.schema.lookup sebagai tempat pertama untuk dokumentasi
dan batasan tingkat-field yang persis. Gunakan Referensi konfigurasi
saat mereka membutuhkan peta konfigurasi yang lebih luas, default, atau tautan ke referensi
subsistem khusus.
config.apply, config.patch, update.run) dibatasi
lajunya menjadi 3 permintaan per 60 detik per deviceId+clientIp. Permintaan
restart digabungkan, lalu memberlakukan cooldown 30 detik antar siklus restart.
update.status bersifat hanya-baca tetapi berada dalam cakupan admin karena sentinel restart dapat
menyertakan ringkasan langkah pembaruan dan ekor output perintah.config.apply maupun config.patch menerima raw, baseHash, sessionKey,
note, dan restartDelayMs. baseHash wajib untuk kedua metode saat
konfigurasi sudah ada.
Variabel lingkungan
OpenClaw membaca env vars dari proses induk plus:.envdari direktori kerja saat ini (jika ada)~/.openclaw/.env(fallback global)
Impor env shell (opsional)
Impor env shell (opsional)
OPENCLAW_LOAD_SHELL_ENV=1Substitusi env var dalam nilai konfigurasi
Substitusi env var dalam nilai konfigurasi
${VAR_NAME}:- Hanya nama huruf besar yang cocok:
[A-Z_][A-Z0-9_]* - Var yang hilang/kosong menimbulkan error saat waktu muat
- Escape dengan
$${VAR}untuk output literal - Berfungsi di dalam file
$include - Substitusi inline:
"${BASE}/v1"→"https://api.example.com/v1"
Referensi rahasia (env, file, exec)
Referensi rahasia (env, file, exec)
secrets.providers untuk env/file/exec) ada di Manajemen Rahasia.
Jalur kredensial yang didukung tercantum di Permukaan Kredensial SecretRef.Referensi lengkap
Untuk referensi lengkap field demi field, lihat Referensi Konfigurasi.Terkait: Contoh Konfigurasi · Referensi Konfigurasi · Doctor