輕鬆搞定 OpenClaw 設定：openclaw config 完全指南

身為開發者，我們最怕的就是手動編輯複雜的設定檔時，因為一個小小的語法錯誤或是縮排問題，導致整個服務崩潰。每次都要反覆檢查 JSON 格式，或是擔心環境變數沒對齊，這種重複且容易出錯的過程真的很消耗開發熱情。

透過 OpenClaw 的 config 工具，你可以更輕鬆地管理 OpenClaw 的設定檔，無論是調整 Gateway 參數還是設定 webhook，都能透過 CLI 指令精準完成，省去手動修改的風險。

範例

你可以直接使用這些指令來快速調整你的設定，這些指令能幫助你精確地操作 openclaw.json 中的各項數值。

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 agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
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 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

config schema

這個指令會將 openclaw.json 對應的 JSON schema 輸出到標準輸出，方便你進行檢查或整合到編輯器工具中。

它包含了當前的根設定 schema、欄位的標題與說明，以及在運行時載入插件與頻道後的元數據，即使目前的設定檔無效，它也能提供一個乾淨的備用 schema。

openclaw config schema

如果你想將其匯出成檔案以便後續檢查，可以使用以下指令：

openclaw config schema > openclaw.schema.json

路徑

設定路徑支援點號或括號表示法，讓你可以輕鬆定位到巢狀結構中的特定欄位。

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

若要針對特定的 agent 進行設定，請使用列表索引：

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

數值

系統會優先以 JSON5 格式解析數值，若無法解析則會視為一般字串，你也可以加上 --strict-json 強制要求 JSON5 解析。

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

若要以 JSON 格式查看原始數值，請在 config get 後加上 --json 參數。

config set 模式

openclaw config set 支援四種不同的賦值風格，包含直接賦值、SecretRef 產生器、Provider 產生器以及批次處理模式。

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

針對 secrets.providers.<alias> 路徑，你可以使用 Provider 產生器模式：

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

你也可以直接傳入 JSON 字串來設定：

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

Provider Builder Flags

當你使用 Provider 產生器時，必須將路徑設為 secrets.providers.<alias>，並根據來源類型設定對應的參數。

若要設定一個強化版的 exec provider，可以參考以下範例：

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

Dry run

在正式寫入檔案前，使用 --dry-run 可以驗證你的變更是否符合 schema 規範以及 SecretRef 是否可解析，避免錯誤設定導致服務中斷。

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

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

若需要機器可讀的報告，請搭配 --json 使用。以下是成功與失敗的輸出範例：

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

{
  "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": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

Write safety

為了確保設定檔的安全性，OpenClaw 在寫入前會進行完整驗證。如果驗證失敗，系統不會覆蓋原有的設定檔，而是將錯誤的內容儲存為 .rejected 檔案。

建議優先使用 CLI 進行小幅度的編輯：

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

若寫入被拒絕，你可以透過以下方式檢查並修復：

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

Subcommands

你可以使用 config file 來確認目前生效的設定檔路徑，修改完成後請記得重新啟動 Gateway。

Validate

在啟動 Gateway 之前，你可以隨時執行驗證指令，確保目前的設定檔符合 schema 要求。

openclaw config validate
openclaw config validate --json

---

下一步

• AI Setup Assistant
• Gateway troubleshooting
• SecretRef Credential Surface