配置

openclaw.json 的非交互式辅助命令：按路径对值执行 get/set/patch/unset、打印 schema、validate，或打印当前活动文件路径。运行不带子命令的 openclaw config 可打开与 openclaw configure 相同的引导式向导。

外部管理的配置¶

当部署系统管理你的配置时，在 Gateway 和所有 OpenClaw CLI 进程的环境中设置 OPENCLAW_CONFIG_READONLY=1：

export OPENCLAW_CONFIG_READONLY=1
openclaw config validate
openclaw gateway run

对于服务或容器，请在其服务环境或容器定义中设置该变量。这是主机环境开关，而不是 openclaw.json 字段。不要在配置 env 或 env.vars 中设置 OPENCLAW_CONFIG_READONLY。env.vars 中的条目会被忽略，包括大小写不同的拼写；扁平的 env 键不是有效配置。配置重载无法启用、禁用或更改由主机选择的只读模式。只有主机值 1 会启用此开关。现有 OPENCLAW_NIX_MODE 行为保持不变。

配置写入会被阻止，包括 setup、onboarding、doctor 修复、插件 install/update/uninstall/enable/disable，以及会修改状态的 openclaw update 流程。启动时派生的默认值仅保留在运行时。请通过外部部署系统修改配置，然后让 Gateway 重新加载配置，或按需重启 Gateway。运行时状态仍需要可写的 OPENCLAW_STATE_DIR。

OPENCLAW_CONFIG_READONLY=1 使用通用的外部管理配置消息，并且不会启用 Nix 特定的安装或服务行为。即使 OPENCLAW_CONFIG_READONLY 未设置或为 0，OPENCLAW_NIX_MODE=1 仍表示配置不可变。对于 Nix 安装，请改为编辑 Nix 源；参见 Nix。

根选项¶

在运行 openclaw config 且不带子命令时，可重复使用的引导式设置部分过滤器。

引导部分：workspace、model、web、gateway、daemon、channels、plugins、skills、health。

示例¶

openclaw config file
openclaw config file --json
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config schema --json
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work '{"cdpPort":18801,"executablePath":"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"}' --strict-json --merge
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set logging.audit.executionIdentity true
openclaw config set 'agents.entries.main.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

路径¶

点号或括号表示法。在 shell 示例中，请为括号路径加引号，以免 zsh 对 [0] 进行 glob 展开：

openclaw config get agents.defaults.workspace
openclaw config get agents.entries.main
openclaw config get agents.entries
openclaw config set 'agents.entries.work.tools.exec.node' "node-id-or-name"

编辑 agent 时，优先使用 agents.entries.<id> 路径。旧版 agents.list[0] 语法和整列表输入在 set、patch 和 unset 中仍然可用；写入会持久化规范的键控名册。索引编辑使用当前名册顺序。在单个批次中，提交的列表会在后续键控编辑中保持其顺序，即使 agent ID 是数字字符串也是如此。现有的名册删除和 $include 所有权保护仍然适用。

当旧版名册在根配置文件中扩展单 agent 安装时，写入会移除其 default 标记，并使用显式所有者保留现有 agent 的职责。显式编写的 ownership: "explicit" 不能与旧版 default: true 标记组合使用。

对于根文件写入，更改 session.store 会清除已复制的 agents.defaults.sessionStore.agentId，因为该所有者属于上一个 store。要为目标 store 分配所有者，请在同一批次中显式设置该所有者路径。无关的写入会保留所有者，包括当 session.store 未设置且按 agent 的默认 store 生效时。已提交且清除所有者的写入会打印警告，其中指明该键和 store 变更。

如果旧版本已经移除了所有者，Doctor 会检查保留的配置备份，并建议恢复与相同已编写 session.store 值对应的最近所有者。恢复需要交互式确认，因为移除可能是有意为之；无人值守的 Doctor 运行会改为显示恢复命令。如果没有可用的备份，legacy-session 发现项会指明 agents.defaults.sessionStore.agentId，以便你显式分配所有者。

config get¶

从已脱敏的配置快照中读取值（机密永不打印）。--json 以 JSON 打印相同的脱敏值；否则字符串/数字/布尔值直接打印，对象/数组以格式化 JSON 打印。

请恰好传递一个配置路径。额外参数（包括空引号参数（""））会被拒绝；它们不会抑制后续选项的验证。

对于 schema 有效但未设置的路径，会说明运行时默认值生效；对于未知路径，会建议运行 openclaw config schema。使用 --json 时，两者都会在 stdout 使用标准 CLI JSON 失败信封 并以状态 1 退出。不使用 --json 时，诊断信息保留在 stderr。

显式的 null、false、0 和空字符串在两种模式下都保持为可读值； --json 会保留它们的类型。没有运行时值的可选字段会被报告为未设置。

openclaw config get browser.executablePath
openclaw config get agents.defaults.model --json

config file¶

打印当前生效的配置文件路径，该路径从 OPENCLAW_CONFIG_PATH 或默认位置解析而来。该路径指向一个常规文件，而不是符号链接；参见 写入安全。

使用 --json 时，stdout 包含一个对象，解析后的路径位于 path 字段下。

config schema¶

将生成的 openclaw.json JSON schema 打印到 stdout。

openclaw config schema
openclaw config schema --json
openclaw config schema > openclaw.schema.json

两种模式下 schema 都是 JSON。--json 被接受为显式的机器输出写法，并让 stdout 仅用于 schema 文档。

config validate¶

来自 config set、config patch 和 config unset 的 schema 拒绝操作会说明受影响的设置，并确认没有保存任何设置。请修正报告的值，或使用 openclaw config schema 查看受支持的设置，然后重试。这些拒绝操作仍以状态 1 退出。显式验证会报告需要修正的设置，而不更改文件；config validate --json 会保留其 valid: false、error 和 issues 字段，供脚本使用。

人工验证诊断会引用字面量记录键，例如 agents.defaults.models["provider/model.v1"].alias，而不是将键内部的点显示为嵌套遍历。数字数组位置使用方括号，例如 agents.entries.main.skills[0]。config validate --json 中的 issues[].path 字段保留其现有的点连接表示。

在不启动 gateway 的情况下，根据当前生效的 schema 验证当前配置。它还会检查每个注册表中声明的 SecretRef 的 provider/source 兼容性，包括已禁用的插件或通道配置。这个严格命令可能会报告一个不活动的不匹配，而该不匹配不会阻止正常的 Gateway 启动；其中 SecretRef 解析仍然仅限于实际生效的表面。

在 schema 验证之后，它会使用与启动时相同的非执行信任检查，检查每个已配置的手动 exec provider 的命令路径：文件是否存在、符号链接、受信任目录、权限、所有权以及 Windows ACL 可用性。config set、config patch 和 config unset 仅将这些检查应用于操作更改或引用的 provider，包括在 dry run 期间。替换 secrets 或 secrets.providers 集合会检查所有剩余 provider。无关的不活动 provider 不会阻止对该 provider 的针对性修复或删除。

路径验证不会执行 provider，也不会验证其输出。通过该检查并不保证 secret 解析成功；exec dry run 需要 --allow-exec 来单独测试这一点。

openclaw config validate
openclaw config validate --json

Provider 和运行时 params 包被有意类型化为 Record<string, unknown>，因为其所有者定义支持的键和值。openclaw config validate 可以验证容器和整体配置形状，但无法对 provider 特定的参数名称或值进行类型检查。通过验证并不能证明某个 param 受支持；请查阅 provider 文档，并在所选运行时和 provider 上验证行为。

值¶

值在可能时按 JSON5 解析；否则被视为原始字符串。使用 --strict-json 可要求标准 JSON，且没有字符串回退（此时会拒绝仅 JSON5 支持的语法，例如注释、尾随逗号或未加引号的键）。在 config set 上，--json 是 --strict-json 的遗留别名。

openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '{"*":{"requireMention":true}}' --strict-json

对于在 shell 中难以加引号的结构化值，请将一个配置形状的 JSON5 对象放入文件，并使用 config patch --file <path> --dry-run。该文件包含配置键及其值，而不是一个裸数组。

config get <path> --json 会以 JSON 形式打印脱敏后的值，而不是终端格式化文本。

当写入更改 agents.defaults.model 或每个 agent 的 agents.entries.*.model 时，OpenClaw 会在写入前通过已配置的目录和所选 provider 的模型解析器，解析每个更改的主模型或回退模型。即使精选选择器中不存在，provider 支持的精确 provider/model 固定值也会被接受；验证不会替换所选模型。未知模型引用会被拒绝，且不会更改当前生效配置。运行 openclaw models list 可浏览选择器，或查阅 provider 文档以获取精确模型 ID。验证成功并不能证明你的账户可以调用该模型。openclaw models set 对同一设置有意更加宽松：它会保存本地目录无法确认的模型，并打印警告，而不是拒绝写入。

向这些映射添加条目时使用 --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。

条件写入¶

当自动化必须仅在某个已编写路径自调用方上次观察以来未发生变化时更新该路径，请使用条件期望：

openclaw config set gateway.port 19001 --strict-json --expect-current-json 18789
openclaw config set gateway.port 19001 --strict-json --expect-current-absent

--expect-current-json <json> 使用严格 JSON，并按 JSON 类型和结构比较值。 null 是已编写值，因此不满足 --expect-current-absent。比较使用在 includes 和环境变量替换之后、运行时默认值应用之前的有效已编写配置。

如果期望不匹配，则不会保存任何设置。重试前请读取当前配置并检查期望值；重复使用相同的错误期望不会成功。

两个期望标志互斥。它们仅适用于单个 config set 操作，要求直接的非重定向配置路径，并且不能与批处理模式或 --dry-run 组合使用。如果输入或名册解析会写入与调用方请求不同的路径， 例如同级 *Ref 路径，命令将以状态 1 退出，而不是重新定向期望。 不匹配时以状态 1 退出，不写入任何内容，也不打印期望值或当前值。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 不会改变批处理解析行为。

提供任一批处理选项即选择批处理模式。空值或仅包含空白字符的值会被拒绝；省略这两个选项以使用位置参数 <path> <value> 模式。

--batch-file 和 config patch --file 使用你提供的确切文件路径，包括前导或尾随空格。在 shell 中为包含空格的路径加引号。

批处理赋值按顺序应用，然后验证检查最终配置。被后续赋值替换的 SecretRef 不会被解析，也不会计入 dry-run 输出，即使使用 --allow-exec 也是如此。仍保留在已更改的 provider 集合中的 provider 仍会接受命令路径信任检查。

JSON 路径/值模式也直接适用于 SecretRef 和 provider：

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> 作为路径。

加固的执行 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

config patch¶

粘贴或通过管道传入符合配置结构的 JSON5 补丁，而不是运行许多基于路径的 config set 命令。对象会递归合并；数组和标量值会替换目标；null 会删除目标路径。

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

补丁文件限制为 8 MiB。通过管道传入的 --stdin 补丁限制为 1 MiB。

为远程设置脚本通过 stdin 管道传入补丁：

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh user@gateway-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-6-astra" },
      models: {
        "openai/gpt-6-astra": {
          agentRuntime: { id: "openclaw" },
          params: { fastMode: true },
        },
      },
    },
  },
}

运行时固定使这成为嵌入式 OpenClaw 配方。有效的 fastMode 值是一种可移植的类型化运行时控制，本身不会选择 OpenClaw。

当某个对象或数组必须精确变为提供的值，而不是被递归补丁时，使用 --replace-path <path>：

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

--dry-run 会运行 schema 和 SecretRef 可解析性检查，而不写入。基于 Exec 的 SecretRef 在试运行期间默认会被跳过；当你有意希望试运行执行 provider 命令时，添加 --allow-exec。

试运行¶

--dry-run 模拟更改而不写入 openclaw.json。可用于 config set、config patch 和 config unset。运行哪些检查取决于输入模式。值模式（不带 --strict-json 的 config set <path> <value>）会跳过完整的 schema 检查和普通的 SecretRef 可解析性扫描。策略、provider 和模型引用检查仍可能运行。当没有检查适用时，值模式即使对于真实写入会拒绝的值也会报告 Dry run successful。当你需要 schema 验证时，使用 --strict-json（或 config patch --file --dry-run）。

对于 config patch 和 config unset，--json 要求 --dry-run。在没有 --dry-run 的情况下使用 --json 会在 stdout 返回标准的 CLI JSON 失败信封，在 stderr 保留诊断信息，并以状态 1 退出。

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" | "unset", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "missing-path" | "schema" | "resolvability" | "model" | "conflict",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

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

{
  "ok": false,
  "operations": 1,
  "configPath": "/home/user/.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"
    }
  ]
}

应用更改¶

在每次成功的 config set / config patch / config unset 之后，CLI 会打印三个提示之一，以便你了解是否需要重启 Gateway：

插件条目更改使用与其他设置相同的重载规划器。在默认 hybrid 模式下，普通的 plugins.entries.<id> 编辑会自动替换受影响的插件 实例。插件更严格的重启策略或 gateway.reload.mode: "off" 仍可能需要重启 Gateway。CLI 提示 描述预期生效方式；它不是来自正在运行的 Gateway 的回执。 参见 配置热重载。

成功的 config set 或 config unset 操作如果没有产生有效的配置差异，会打印 No change，并保持 JSON5 文件逐字节不变。如果 config unset 的目标在已编写的配置中不存在，则以状态 1 退出，并且同样保持文件不变。将不存在的键设置为等于其运行时默认值的值仍然是一次已编写的更改，并会持久化显式值。

写入安全¶

openclaw config set 和其他由 OpenClaw 拥有的配置写入器在将更改提交到磁盘之前，会验证完整的更改后配置。如果新负载未通过模式验证，或看起来像破坏性覆盖，则活动配置保持不变，被拒绝的负载会作为 openclaw.json.rejected.* 保存在其旁边。

如果暂存配置保存失败，现有的根或 include 备份环将保持 不变。OpenClaw 会在不阻塞无关 Gateway 请求的情况下准备备份内容。如果复制回退在冲突前删除了文件，OpenClaw 会在其仍拥有缺失目标时恢复 原始文件。否则，错误 会报告部分发布以及另一次保存前需要检查的备份位置。

如果文件已保存但后续处理失败，错误会指明已写入的文件 并报告写入是否已回滚。当某个包含的文件拥有被编辑的设置时，这可能会指明该包含文件。如果回滚未发生或无法 确认，请在重试前检查所指明的文件和活动配置。

由 OpenClaw 拥有的、更改配置的写入会将 JSON5 重新序列化为标准 JSON。当源包含注释时，写入器会在删除注释前立即发出警告；当需要保留注释时，请使用直接编辑器。

对于小编辑，优先使用 CLI 写入：

openclaw config set gateway.reload.mode '"hybrid"' --strict-json --dry-run
openclaw config set gateway.reload.mode '"hybrid"' --strict-json
openclaw config validate

如果写入被拒绝，请检查已保存的负载并修正完整的配置结构：

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

仍允许直接编辑器写入，但正在运行的 Gateway 在它们通过验证之前会将其视为不受信任。启动时会验证配置，而不会重写旧版键。无效的直接编辑会阻止启动；热重载会跳过无效编辑，而不会重写 openclaw.json。运行 openclaw doctor --fix 以修复旧版键、带前缀/被覆盖的配置，或恢复最后已知良好状态。参见 Gateway 故障排除。

普通恢复可以逐字恢复符合条件的有效当前备份。需要旧版转换的备份必须通过 Doctor 恢复。插件模式更改或 minHostVersion 偏差会保持明显提示，而不是回滚无关的用户设置，例如模型、提供商、身份验证配置文件、通道、网关暴露、工具、内存、浏览器或 cron 配置。

修复循环¶

在 openclaw config validate 通过后，使用本地 TUI 让嵌入式代理将活动配置与文档进行比较，同时你在同一终端中验证每项更改：

openclaw chat

在 TUI 中，开头的 ! 会执行字面本地 shell 命令（每次会话仅确认一次）：

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

1. 与文档对比

让代理将当前配置与相关文档页面进行对比，并建议最小的修复方案。

2. 应用针对性修改

使用 openclaw config set 或 openclaw configure 应用针对性修改。

3. 重新验证

每次更改后重新运行 openclaw config validate。

4. 使用 doctor 排查运行时问题

如果验证通过但运行时仍不健康，请运行 openclaw doctor 或 openclaw doctor --fix 以获取迁移和修复帮助。

相关¶

• CLI 参考
• 配置
• openclaw configure — 用于相同设置的引导式编辑器