Konfigurasi

Pembantu non-interaktif untuk openclaw.json: mendapatkan/menetapkan/menambal/menghapus penetapan nilai berdasarkan jalur, mencetak skema, memvalidasi, atau mencetak jalur file aktif. Jalankan openclaw config tanpa subperintah untuk membuka wisaya terpandu yang sama seperti openclaw configure.

Saat OPENCLAW_NIX_MODE=1, OpenClaw memperlakukan openclaw.json sebagai tidak dapat diubah. Perintah hanya-baca (config get, config file, config schema, config validate) tetap berfungsi; penulis konfigurasi akan menolak. Sebagai gantinya, edit sumber Nix untuk instalasi tersebut; untuk distribusi nix-openclaw pihak pertama, gunakan Panduan Mulai Cepat nix-openclaw dan tetapkan nilai di bawah programs.openclaw.config atau instances.<name>.config.

Opsi root

string

Filter bagian penyiapan terpandu yang dapat diulang saat Anda menjalankan openclaw config tanpa subperintah.

Bagian terpandu: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Contoh

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

Jalur

Notasi titik atau tanda kurung. Kutip jalur bertanda kurung dalam contoh shell agar zsh tidak memperluas pola glob [0]:

openclaw config get agents.defaults.workspace
openclaw config get 'agents.list[0].id'
openclaw config get agents.list
openclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

`config get`

Membaca nilai dari snapshot konfigurasi yang telah disunting (rahasia tidak pernah dicetak). --json mencetak nilai mentah sebagai JSON; jika tidak, string/angka/boolean dicetak apa adanya dan objek/larik dicetak sebagai JSON berformat. Saat jalur tidak ditemukan, --json menulis { "error": "Config path not found: <path>" } ke stdout dan keluar dengan status 1. Tanpa --json, diagnostik tetap berada di stderr.

openclaw config get browser.executablePath
openclaw config get agents.defaults.model --json

`config file`

Mencetak jalur file konfigurasi aktif, yang diselesaikan dari OPENCLAW_CONFIG_PATH atau lokasi default. Jalur tersebut menunjuk ke file biasa, bukan symlink; lihat Keamanan penulisan.

`config schema`

Mencetak skema JSON yang dihasilkan untuk openclaw.json ke stdout.

Yang disertakan

Skema konfigurasi root saat ini, ditambah bidang string root $schema untuk alat editor.
Metadata dokumentasi bidang title / description yang digunakan oleh UI Kontrol.
Node objek bersarang, wildcard (*), dan item larik ([]) mewarisi metadata title / description yang sama ketika dokumentasi bidang yang cocok tersedia.
Cabang anyOf / oneOf / allOf juga mewarisi metadata dokumentasi yang sama.
Metadata skema plugin + saluran langsung dengan upaya terbaik saat manifes runtime dapat dimuat.
Skema cadangan yang bersih bahkan ketika konfigurasi saat ini tidak valid.

RPC runtime terkait

config.schema.lookup mengembalikan satu jalur konfigurasi yang dinormalisasi dengan node skema dangkal (title, description, type, enum, const, batas umum), metadata petunjuk UI yang cocok, dan ringkasan turunan langsung. Gunakan untuk penelusuran mendalam dalam cakupan jalur di UI Kontrol atau klien khusus.

openclaw config schema
openclaw config schema > openclaw.schema.json

`config validate`

Memvalidasi konfigurasi saat ini terhadap skema aktif tanpa memulai Gateway.

openclaw config validate
openclaw config validate --json

Jika validasi sudah gagal, mulai dengan openclaw configure atau openclaw doctor --fix. openclaw chat tidak melewati pengaman konfigurasi tidak valid.

Nilai

Nilai diuraikan sebagai JSON5 jika memungkinkan; jika tidak, nilai diperlakukan sebagai string mentah. Gunakan --strict-json untuk mewajibkan JSON standar tanpa fallback string (sintaks khusus JSON5 seperti komentar, koma di akhir, atau kunci tanpa tanda kutip kemudian ditolak). --json adalah alias lama untuk --strict-json pada config set.

openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json mencetak nilai mentah sebagai JSON, bukan teks yang diformat untuk terminal. Saat penulisan mengubah agents.defaults.model atau agents.list[].model per agen, OpenClaw menyelesaikan setiap pilihan utama atau fallback yang berubah melalui katalog penyedia yang dikonfigurasi sebelum menulis. Referensi model yang tidak dikenal ditolak tanpa mengubah konfigurasi aktif; jalankan openclaw models list untuk melihat model yang tersedia.

Penetapan objek mengganti jalur target secara default. Jalur terlindungi yang biasanya menampung entri tambahan pengguna menolak penggantian yang akan menghapus entri yang ada kecuali Anda meneruskan --replace: agents.defaults.models, agents.list, models.providers, models.providers.<id>, models.providers.<id>.models, plugins.entries, dan auth.profiles.

Gunakan --merge saat menambahkan entri ke peta tersebut:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

Gunakan --replace hanya ketika nilai yang diberikan memang dimaksudkan menjadi nilai target lengkap.

Mode `config set`

Mode nilai
Mode pembuat SecretRef
Mode pembuat penyedia
Mode batch

openclaw config set <path> <value>

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN

Hanya menargetkan jalur secrets.providers.<alias>:

openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-timeout-ms 5000

openclaw config set --batch-json '[
  {
    "path": "secrets.providers.default",
    "provider": { "source": "env" }
  },
  {
    "path": "channels.discord.token",
    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
  }
]'

openclaw config set --batch-file ./config-set.batch.json --dry-run

File batch dibatasi hingga 8 MiB.

Penetapan SecretRef ditolak pada permukaan yang dapat diubah saat runtime yang tidak didukung (misalnya hooks.token, commands.ownerDisplaySecret, token Webhook pengikatan utas Discord, dan JSON kredensial WhatsApp). Lihat Permukaan Kredensial SecretRef.

Penguraian batch selalu menggunakan payload batch (--batch-json/--batch-file) sebagai sumber kebenaran; --strict-json / --json tidak mengubah perilaku penguraian batch. Mode jalur/nilai JSON juga berfungsi langsung untuk SecretRef dan penyedia:

openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

Flag pembuat penyedia

Target pembuat penyedia harus menggunakan secrets.providers.<alias> sebagai jalur.

Flag umum

--provider-source <env|file|exec>
--provider-timeout-ms <ms> (file, exec)

Penyedia env (--provider-source env)

--provider-allowlist <ENV_VAR> (dapat diulang)

Penyedia file (--provider-source file)

--provider-path <path> (wajib)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>
--provider-allow-insecure-path

Penyedia exec (--provider-source exec)

--provider-command <path> (wajib)
--provider-arg <arg> (dapat diulang)
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE> (dapat diulang)
--provider-pass-env <ENV_VAR> (dapat diulang)
--provider-trusted-dir <path> (dapat diulang)
--provider-allow-insecure-path
--provider-allow-symlink-command

Contoh penyedia exec yang diperkuat:

openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

`config patch`

Tempelkan atau salurkan tambalan JSON5 berbentuk konfigurasi alih-alih menjalankan banyak perintah config set berbasis jalur. Objek digabungkan secara rekursif; larik dan nilai skalar mengganti target; null menghapus jalur target.

openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5

File tambalan dibatasi hingga 8 MiB. Tambalan --stdin yang disalurkan dibatasi hingga 1 MiB. Salurkan tambalan melalui stdin untuk skrip penyiapan jarak jauh:

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Contoh tambalan:

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
      models: {
        "openai/gpt-5.6-sol": { params: { fastMode: true } },
      },
    },
  },
}

Gunakan --replace-path <path> ketika satu objek atau larik harus menjadi persis nilai yang diberikan, alih-alih ditambal secara rekursif:

openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run menjalankan pemeriksaan skema dan kemampuan resolusi SecretRef tanpa menulis. SecretRef berbasis exec dilewati secara default selama uji coba; tambahkan --allow-exec jika Anda memang ingin uji coba menjalankan perintah penyedia.

Uji coba

--dry-run memvalidasi perubahan tanpa menulis openclaw.json. Tersedia pada config set, config patch, dan config unset.

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec

Perilaku uji coba

Mode builder: menjalankan pemeriksaan kemampuan resolusi SecretRef untuk referensi/penyedia yang diubah.
Mode JSON (--strict-json, --json, atau mode batch): menjalankan validasi skema beserta pemeriksaan kemampuan resolusi SecretRef.
Validasi kebijakan dijalankan terhadap konfigurasi lengkap setelah perubahan, sehingga penulisan objek induk (misalnya menetapkan hooks sebagai objek) tidak dapat melewati validasi permukaan yang tidak didukung.
Pemeriksaan SecretRef exec dilewati secara default untuk menghindari efek samping perintah; teruskan --allow-exec untuk mengaktifkannya (ini dapat menjalankan perintah penyedia). --allow-exec hanya untuk uji coba dan menghasilkan kesalahan tanpa --dry-run.

Kolom --dry-run --json

ok: apakah uji coba berhasil
operations: jumlah penetapan yang dievaluasi
checks: apakah pemeriksaan skema/kemampuan resolusi dijalankan
checks.resolvabilityComplete: apakah pemeriksaan kemampuan resolusi dijalankan hingga selesai (false ketika referensi exec dilewati)
refsChecked: jumlah referensi yang benar-benar diresolusi selama uji coba
skippedExecRefs: jumlah referensi exec yang dilewati karena --allow-exec tidak ditetapkan
errors: kegagalan jalur yang hilang, skema, atau kemampuan resolusi yang terstruktur ketika ok=false

Bentuk keluaran JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder" | "unset", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "missing-path" | "schema" | "resolvability" | "model",
      message: string,
      ref?: string, // tersedia untuk kesalahan kemampuan resolusi
    },
  ],
}

Contoh berhasil
Contoh kegagalan

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}

{
  "ok": false,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0,
  "errors": [
    {
      "kind": "resolvability",
      "message": "Kesalahan: Variabel lingkungan \"MISSING_TEST_SECRET\" tidak ditetapkan.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

Jika uji coba gagal

config schema validation failed: bentuk konfigurasi setelah perubahan tidak valid; perbaiki jalur/nilai atau bentuk objek penyedia/referensi.
Config policy validation failed: unsupported SecretRef usage: pindahkan kredensial tersebut kembali ke masukan teks biasa/string; gunakan SecretRef hanya pada permukaan yang didukung.
SecretRef assignment(s) could not be resolved: penyedia/referensi yang dirujuk saat ini tidak dapat diresolusi (variabel lingkungan tidak ada, penunjuk berkas tidak valid, kegagalan penyedia exec, atau ketidakcocokan penyedia/sumber).
model reference validation failed: model teks utama atau cadangan yang diubah tidak dikenali; jalankan openclaw models list dan pilih model yang tersedia.
Dry run note: skipped <n> exec SecretRef resolvability check(s): jalankan ulang dengan --allow-exec jika Anda memerlukan validasi kemampuan resolusi exec.
Untuk mode batch, perbaiki entri yang gagal dan jalankan ulang --dry-run sebelum menulis.

Menerapkan perubahan

Setelah setiap config set / config patch / config unset berhasil, CLI mencetak salah satu dari tiga petunjuk agar Anda mengetahui apakah Gateway perlu dimulai ulang:

Petunjuk	Arti
`Restart the gateway to apply.`	Jalur yang diubah memerlukan mulai ulang penuh.
`Change will apply without restarting the gateway.`	Pemuatan ulang langsung menerapkannya otomatis.
`No gateway restart needed.`	Tidak ada perubahan yang relevan bagi runtime.

Penulisan ke plugins.entries (atau subjalur apa pun) selalu memerlukan mulai ulang karena CLI tidak dapat membuktikan bahwa metadata pemuatan ulang setiap plugin telah dimuat.

Keamanan penulisan

openclaw config set dan penulis konfigurasi lain yang dimiliki OpenClaw memvalidasi konfigurasi lengkap setelah perubahan sebelum menyimpannya ke disk. Jika muatan baru gagal dalam validasi skema atau tampak seperti penimpaan destruktif, konfigurasi aktif tidak diubah dan muatan yang ditolak disimpan di sebelahnya sebagai openclaw.json.rejected.*. Penulisan yang dimiliki OpenClaw melakukan serialisasi ulang JSON5 sebagai JSON standar. Jika sumber berisi komentar, penulis akan langsung memperingatkan sebelum menghapusnya; gunakan editor langsung jika komentar perlu dipertahankan.

Jalur konfigurasi aktif harus berupa berkas biasa. Tata letak openclaw.json yang menggunakan symlink tidak didukung untuk penulisan; sebagai gantinya, gunakan OPENCLAW_CONFIG_PATH untuk menunjuk langsung ke berkas sebenarnya.

Utamakan penulisan melalui CLI untuk pengeditan kecil:

openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

Jika penulisan ditolak, periksa muatan yang disimpan dan perbaiki bentuk konfigurasi lengkap:

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate

Penulisan melalui editor langsung tetap diizinkan, tetapi Gateway yang sedang berjalan menganggapnya tidak tepercaya hingga berhasil divalidasi. Pengeditan langsung yang tidak valid menyebabkan kegagalan saat memulai atau dilewati oleh pemuatan ulang langsung; Gateway tidak menulis ulang openclaw.json. Jalankan openclaw doctor --fix untuk memperbaiki konfigurasi yang memiliki prefiks/tertimpa atau memulihkan salinan terakhir yang diketahui valid. Lihat Pemecahan masalah Gateway. Pemulihan seluruh berkas hanya diperuntukkan bagi perbaikan oleh doctor. Perubahan skema plugin atau ketidakselarasan minHostVersion tetap menghasilkan kegagalan yang jelas alih-alih mengembalikan pengaturan pengguna lain yang tidak terkait, seperti konfigurasi model, penyedia, profil autentikasi, saluran, eksposur Gateway, alat, memori, browser, atau cron.

Siklus perbaikan

Setelah openclaw config validate berhasil, gunakan TUI lokal agar agen tertanam membandingkan konfigurasi aktif dengan dokumentasi sembari Anda memvalidasi setiap perubahan dari terminal yang sama:

openclaw chat

Di dalam TUI, awalan ! menjalankan perintah shell lokal secara literal (setelah permintaan konfirmasi satu kali per sesi):

!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

Bandingkan dengan dokumentasi

Minta agen membandingkan konfigurasi Anda saat ini dengan halaman dokumentasi yang relevan dan menyarankan perbaikan terkecil.

Terapkan pengeditan tertarget

Terapkan pengeditan tertarget dengan openclaw config set atau openclaw configure.

Validasi ulang

Jalankan ulang openclaw config validate setelah setiap perubahan.

Gunakan doctor untuk masalah runtime

Jika validasi berhasil tetapi runtime masih bermasalah, jalankan openclaw doctor atau openclaw doctor --fix untuk mendapatkan bantuan migrasi dan perbaikan.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Opsi root

Contoh

Jalur

`config get`

`config file`

`config schema`

`config validate`

Nilai

Mode `config set`

Flag pembuat penyedia

`config patch`

Uji coba

Bentuk keluaran JSON

Menerapkan perubahan

Keamanan penulisan

Siklus perbaikan

Terkait

​Opsi root

​Contoh

​Jalur

​config get

​config file

​config schema

​config validate

​Nilai

​Mode config set

​Flag pembuat penyedia

​config patch

​Uji coba

​Bentuk keluaran JSON

​Menerapkan perubahan

​Keamanan penulisan

​Siklus perbaikan

​Terkait

Opsi root

Contoh

Jalur

`config get`

`config file`

`config schema`

`config validate`

Nilai

Mode `config set`

Flag pembuat penyedia

`config patch`

Uji coba

Bentuk keluaran JSON

Menerapkan perubahan

Keamanan penulisan

Siklus perbaikan

Terkait