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 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.

Opsi root

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 tanda kurung. Kutip jalur bertanda kurung 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 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.

bash
openclaw config get browser.executablePathopenclaw 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.

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 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.

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.

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.

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

File batch dibatasi hingga 8 MiB.

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:

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 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 &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 exec 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

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.

bash
openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw 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:

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, alih-alih ditambal secara rekursif:

bash
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.

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 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

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" | "model",      message: string,      ref?: string, // tersedia untuk kesalahan kemampuan resolusi    },  ],}

Contoh berhasil

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": "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.

Utamakan penulisan melalui CLI untuk pengeditan 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 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:

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 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.

    • Terkait

    Was this useful?
    On this page

    On this page