設定

openclaw.json 中用於非互動式編輯的設定輔助工具：依路徑取得/設定/修補/取消設定/檔案/結構描述/驗證值，並列印作用中的設定檔。不帶子命令執行時，會開啟設定精靈（等同於 openclaw configure）。

# 根選項

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> 當你執行不帶子命令的 openclaw config 時，可重複使用的引導式設定區段篩選器。

支援的引導式區段：workspace、model、web、gateway、daemon、channels、plugins、skills、health。

# 範例

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

# config schema

將為 openclaw.json 產生的 JSON 結構描述以 JSON 形式列印到 stdout。

openclaw config schema

若你想用其他工具檢查或驗證它，可將其透過管線輸出到檔案：

openclaw config schema > openclaw.schema.json

# 路徑

路徑使用點記法或括號記法：

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

使用 agent 清單索引來指定特定 agent：

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

# 值

值會在可能時解析為 JSON5；否則會被視為字串。使用 --strict-json 要求 JSON5 解析。--json 仍支援作為舊版別名。

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 會以 JSON 列印原始值，而不是終端格式化文字。

將項目加入這些 map 時，請使用 --merge：

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

只有在你刻意希望提供的值成為完整目標值時，才使用 --replace。

# config set 模式

openclaw config set 支援四種指派樣式：

openclaw config set <path> <value>

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

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

批次解析一律使用批次承載（--batch-json/--batch-file）作為事實來源。--strict-json / --json 不會改變批次解析行為。

# config patch

當你想貼上或透過管線傳入設定形狀的修補，而不是執行許多基於路徑的 config set 命令時，請使用 config patch。輸入是 JSON5 物件。物件會遞迴合併，陣列和純量值會取代目標值，而 null 會刪除目標路徑。

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

你也可以透過 stdin 傳入修補，這對遠端設定腳本很有用：

ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.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.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}

當某個物件或陣列必須精確成為提供的值，而不是被遞迴修補時，請使用 --replace-path <path>：

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

--dry-run 會在不寫入的情況下執行結構描述和 SecretRef 可解析性檢查。在 dry-run 期間，預設會略過 exec 後端的 SecretRef；當你刻意希望 dry-run 執行 provider 命令時，請加入 --allow-exec。

JSON 路徑/值模式仍同時支援 SecretRefs 和 providers：

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 建構器旗標

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 可在不寫入 openclaw.json 的情況下驗證變更。

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"
    }
  ]
}

# 寫入安全性

openclaw config set 和其他 OpenClaw 擁有的設定寫入器，會在提交到磁碟前驗證完整的變更後設定。如果新的 payload 未通過結構描述驗證，或看起來像破壞性覆寫，作用中的設定會保持不變，而被拒絕的 payload 會以 openclaw.json.rejected.* 儲存在旁邊。

小幅編輯建議使用 CLI 寫入：

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

如果寫入遭拒，請檢查儲存的 payload 並修正完整設定形狀：

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

仍允許直接用編輯器寫入，但執行中的 Gateway 在驗證通過前會將其視為不受信任。無效的直接編輯會導致啟動失敗，或被熱重載略過；Gateway 不會重寫 openclaw.json。執行 openclaw doctor --fix 來修復加上前綴/遭覆寫的設定，或還原最後已知良好的副本。請參閱 Gateway 疑難排解。

整檔復原僅保留給 doctor 修復使用。Plugin 結構描述變更或 minHostVersion 偏差會保持明確報錯，而不是回復不相關的使用者設定，例如 models、providers、auth profiles、channels、gateway exposure、tools、memory、browser 或 cron config。

# 子命令

• config file: 列印作用中的設定檔路徑（由 OPENCLAW_CONFIG_PATH 或預設位置解析）。該路徑應指向一般檔案，而不是符號連結。

編輯後請重新啟動 Gateway。

# 驗證

在不啟動 Gateway 的情況下，依作用中結構描述驗證目前設定。

openclaw config validate
openclaw config validate --json

當 openclaw config validate 已通過後，你可以使用本機 TUI，讓內嵌代理程式在同一個終端機中協助你驗證每項變更時，比對作用中設定與文件：

openclaw chat

然後在 TUI 內：

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

典型修復流程：

# 相關

• CLI 參考
• 設定