OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Konfigurasi

Pembantu noninteraktif untuk openclaw.json: mendapatkan/mengatur/menambal/menghapus nilai berdasarkan jalur, mencetak skema, memvalidasi, atau mencetak jalur berkas aktif. Jalankan openclaw config tanpa subperintah untuk membuka wizard terpandu yang sama seperti openclaw configure.

Opsi akar

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="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

bash
openclaw config fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw 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 --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json

Jalur

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

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

config get

Membaca nilai dari snapshot konfigurasi yang telah disamarkan (rahasia tidak pernah dicetak). --json mencetak nilai mentah sebagai JSON; jika tidak digunakan, string/angka/boolean dicetak tanpa pembungkus, sedangkan objek/larik dicetak sebagai JSON berformat.

bash
openclaw config get browser.executablePathopenclaw config get agents.defaults.model --json

config file

Mencetak jalur berkas konfigurasi aktif, yang ditentukan dari OPENCLAW_CONFIG_PATH atau lokasi bawaan. Jalur tersebut menunjuk ke berkas biasa, bukan symlink; lihat Keamanan penulisan.

config schema

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

Yang disertakan
  • Skema konfigurasi akar saat ini, ditambah bidang string $schema pada akar untuk perangkat editor.
  • Metadata dokumentasi bidang title / description yang digunakan oleh UI Kontrol.
  • Node objek bertingkat, 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 secara upaya terbaik ketika manifes runtime dapat dimuat.
  • Skema cadangan yang bersih meskipun 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 anak langsung. Gunakan untuk penelusuran mendalam yang dibatasi jalur di UI Kontrol atau klien khusus.

bash
openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

Memvalidasi konfigurasi saat ini terhadap skema aktif tanpa memulai Gateway.

bash
openclaw config validateopenclaw config validate --json

Nilai

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

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

config get <path> --json mencetak nilai mentah sebagai JSON, bukan teks yang diformat untuk terminal.

Gunakan --merge saat menambahkan entri ke peta tersebut:

bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw 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

bash
openclaw config set <path> <value>

Mode pembuat SecretRef

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

Mode pembuat penyedia

Hanya menargetkan jalur secrets.providers.<alias>:

bash
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

Mode batch

bash
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" }  }]'
bash
openclaw config set --batch-file ./config-set.batch.json --dry-run

Penguraian batch selalu menggunakan muatan 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:

bash
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 &lt;ENV_VAR&gt; (dapat diulang)
Penyedia berkas (--provider-source file)
  • --provider-path <path> (wajib)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
Penyedia eksekusi (--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 &lt;KEY=VALUE&gt; (dapat diulang)
  • --provider-pass-env &lt;ENV_VAR&gt; (dapat diulang)
  • --provider-trusted-dir <path> (dapat diulang)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command

Contoh penyedia eksekusi yang diperkuat:

bash
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

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

bash
openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5

Salurkan tambalan melalui stdin untuk skrip penyiapan jarak jauh:

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

Contoh tambalan:

json5
{  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, bukan ditambal secara rekursif:

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

--dry-run menjalankan pemeriksaan skema dan keteruraian SecretRef tanpa menulis. SecretRef yang didukung eksekusi dilewati secara bawaan selama uji coba; tambahkan --allow-exec ketika Anda memang menginginkan uji coba menjalankan perintah penyedia.

Uji coba

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

bash
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 pembangun: menjalankan pemeriksaan keteruraian SecretRef untuk referensi/penyedia yang diubah.
  • Mode JSON (--strict-json, --json, atau mode batch): menjalankan validasi skema beserta pemeriksaan keteruraian 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 bawaan untuk menghindari efek samping perintah; teruskan --allow-exec untuk mengaktifkannya (ini dapat menjalankan perintah penyedia). --allow-exec hanya berlaku untuk uji coba dan menghasilkan galat tanpa --dry-run.
Bidang --dry-run --json
  • ok: apakah uji coba berhasil
  • operations: jumlah penetapan yang dievaluasi
  • checks: apakah pemeriksaan skema/keteruraian dijalankan
  • checks.resolvabilityComplete: apakah pemeriksaan keteruraian berjalan hingga selesai (false saat referensi exec dilewati)
  • refsChecked: jumlah referensi yang benar-benar diuraikan selama uji coba
  • skippedExecRefs: jumlah referensi exec yang dilewati karena --allow-exec tidak ditetapkan
  • errors: kegagalan jalur yang hilang, skema, atau keteruraian yang terstruktur saat ok=false

Bentuk keluaran JSON

json5
{  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",      message: string,      ref?: string, // present for resolvability errors    },  ],}

Contoh keberhasilan

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

Contoh kegagalan

json
{  "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": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",      "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: kembalikan kredensial tersebut 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 diuraikan (variabel lingkungan hilang, penunjuk berkas tidak valid, kegagalan penyedia exec, atau ketidakcocokan penyedia/sumber).
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): jalankan ulang dengan --allow-exec jika Anda memerlukan validasi keteruraian 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. Muat ulang langsung menerapkannya secara 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 memastikan bahwa metadata muat ulang setiap plugin telah dimuat.

Keamanan penulisan

openclaw config set dan penulis konfigurasi milik OpenClaw lainnya 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.*.

Utamakan penulisan melalui CLI untuk penyuntingan kecil:

bash
openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

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

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

Penulisan langsung melalui editor tetap diizinkan, tetapi Gateway yang berjalan memperlakukannya sebagai tidak tepercaya hingga tervalidasi. Penyuntingan langsung yang tidak valid menyebabkan kegagalan saat memulai atau dilewati oleh muat ulang langsung; Gateway tidak menulis ulang openclaw.json. Jalankan openclaw doctor --fix untuk memperbaiki konfigurasi yang diberi prefiks/tertimpa atau memulihkan salinan terakhir yang diketahui baik. Lihat pemecahan masalah Gateway.

Pemulihan seluruh berkas hanya digunakan untuk perbaikan oleh doctor. Perubahan skema Plugin atau ketidakselarasan minHostVersion tetap memunculkan kegagalan secara jelas alih-alih mengembalikan pengaturan pengguna lain yang tidak terkait, seperti konfigurasi model, penyedia, profil autentikasi, saluran, eksposur gateway, alat, memori, peramban, atau cron.

Siklus perbaikan

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

bash
openclaw chat

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

text
!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 penyuntingan terarah

    Terapkan penyuntingan terarah 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 bantuan migrasi dan perbaikan.

    • Terkait

    Was this useful?
    On this page

    On this page