配置

用于在 openclaw.json 中进行非交互式编辑的配置辅助工具：通过路径获取/设置/修补/取消设置/文件/架构/验证值，并打印活动配置文件。不带子命令运行以打开配置向导（与 openclaw configure 相同）。

根选项

当您不带子命令运行 `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 格式打印到标准输出。

包含内容

当前的根配置模式，以及一个用于编辑器工具的根 $schema 字符串字段。
Control UI 使用的字段 title 和 description 文档元数据。
嵌套对象、通配符 (*) 和数组项 ([]) 节点在存在匹配字段文档时继承相同的 title / description 元数据。
anyOf / oneOf / allOf 分支在存在匹配字段文档时也继承相同的文档元数据。
当可以加载运行时清单时，尽力提供实时的插件 + 渠道模式元数据。
即使当前配置无效，也会提供一个干净的后备模式。

RPC相关运行时 RPC

config.schema.lookup 返回一个带有浅层模式节点（title、description、type、enum、const、通用边界）的标准化配置路径、匹配的 UI 提示元数据以及直接子摘要。使用它可在 Control UI 或自定义客户端中进行路径范围的向下钻取。

openclaw config schema

当您想使用其他工具检查或验证它时，将其通过管道传输到文件中：

openclaw config schema > openclaw.schema.json

路径

路径使用点或括号表示法：

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"

值

值在可能的情况下被解析为 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

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

Provider builder 模式仅针对 `secrets.providers.

` 路径：

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

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 可解析性检查而不进行写入。在试运行期间默认跳过 Exec 支持的 SecretRefs；当您有意想让试运行执行提供商命令时，请添加 --allow-exec。

对于 SecretRefs 和提供商，仍然支持 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

提供商构建器标志

提供商构建器目标必须使用 secrets.providers.<alias> 作为路径。

通用标志

`—provider-source

-—provider-timeout-ms

(file, exec`)

Env 提供商 (--提供商-source env)

`—provider-allowlist

` (可重复)

File 提供商 (--提供商-source file)

`—provider-path

(必需) -—provider-mode

-—provider-max-bytes

-—provider-allow-insecure-path`

Exec 提供商 (--提供商-source exec)

`—provider-command

(必需) -—provider-arg

(可重复) -—provider-no-output-timeout-ms

-—provider-max-output-bytes

-—provider-json-only -—provider-env

(可重复) -—provider-pass-env

(可重复) -—provider-trusted-dir

(可重复) -—provider-allow-insecure-path -—provider-allow-symlink-command`

硬化的 exec 提供商示例：

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 在不写入 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

Dry-run behavior

Builder 模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。
JSON 模式（--strict-json、--json 或 batch 模式）：运行架构验证以及 SecretRef 可解析性检查。
策略验证也会针对已知的不受支持的 SecretRef 目标表面运行。
策略检查评估完整的更改后配置，因此父对象写入（例如将 hooks 设置为对象）无法绕过不受支持表面的验证。
默认情况下，试运行期间会跳过 Exec SecretRef 检查以避免命令副作用。
将 --allow-exec 与 --dry-run 配合使用以启用 Exec SecretRef 检查（这可能会执行提供商命令）。
--allow-exec 仅用于试运行，如果在不使用 --dry-run 的情况下使用则会报错。

--dry-run -- fields

--dry-run --json 打印机器可读的报告：

ok：dry-run 是否通过
operations：评估的赋值数量
checks：是否运行了 schema/可解析性检查
checks.resolvabilityComplete：可解析性检查是否运行完成（跳过 exec refs 时为 false）
refsChecked：dry-run 期间实际解析的 refs 数量
skippedExecRefs：因未设置 --allow-exec 而跳过的 exec refs 数量
errors：当 ok=false 时结构化的缺失路径、schema 或可解析性失败信息

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

If dry-run fails

config schema validation failed：您更改后的配置形状无效；请修复路径/值或提供商/ref 对象的形状。
Config policy validation failed: unsupported SecretRef usage：将该凭据移回纯文本/字符串输入，并仅将 SecretRefs 保留在支持的表面上。
SecretRef assignment(s) could not be resolved：引用的提供商/ref 当前无法解析（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/源不匹配）。
`Dry run note: skipped

exec SecretRef resolvability check(s)：试运行跳过了 exec 引用；如果您需要 exec 可解析性验证，请使用 —allow-exec` 重新运行。

对于批处理模式，请修复失败的条目，并在写入前重新运行 --dry-run。

写入安全

openclaw config set 和其他 OpenClaw 拥有的配置写入程序会在将更改后的完整配置提交到磁盘之前对其进行验证。如果新负载未通过架构验证或看起来像是具有破坏性的覆盖，活动配置将保持不变，被拒绝的负载将作为 openclaw.json.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

仍然允许直接通过编辑器写入，但在其通过验证之前，运行的 Gateway(网关) 将其视为不受信任。无效的直接编辑会导致启动失败或被热重载跳过；Gateway(网关) 不会重写 openclaw.json。运行 openclaw doctor --fix 以修复带前缀/被覆盖的配置或恢复最后一个已知完好的副本。请参阅 Gateway(网关) 故障排除。

全文件恢复保留给 doctor 修复。插件架构更改或 minHostVersion 偏差会保持提示，而不是回滚无关的用户设置，例如模型、提供商、身份验证配置文件、通道、网关暴露、工具、内存、浏览器或 cron 配置。

子命令

config file：打印活动配置文件路径（从 OPENCLAW_CONFIG_PATH 或默认位置解析）。路径应指向常规文件，而不是符号链接。

编辑后重启网关。

验证

根据活动架构验证当前配置，而无需启动网关。

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

典型修复循环：

与文档比较
要求代理将您的当前配置与相关文档页面进行比较，并提出最小的修复建议。
应用有针对性的编辑
使用 openclaw config set 或 openclaw configure 应用有针对性的编辑。
重新验证
在每次更改后重新运行 openclaw config validate。
运行时问题的 Doctor
如果验证通过但运行时仍然不正常，请运行 openclaw doctor 或 openclaw doctor --fix 以获取迁移和修复帮助。