配置 - OpenClaw 中文文档

用于 openclaw.json 的非交互式辅助命令：可按路径获取/设置/补丁/取消设置某个值，打印 schema，验证，或打印当前活动文件路径。无子命令运行 openclaw config 时，会打开与 openclaw configure 相同的引导式向导。

当 OPENCLAW_NIX_MODE=1 时，OpenClaw 会将 openclaw.json 视为不可变。只读命令（config get、config file、config schema、config validate）仍可工作；配置写入命令会拒绝执行。请改为编辑安装所使用的 Nix 源；对于第一方的 nix-openclaw 发行版，请使用 nix-openclaw 快速开始，并在 programs.openclaw.config 或 instances.<name>.config 下设置值。

根选项

string

可复用的引导式设置部分筛选器，在不带子命令运行 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.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
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]：

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"

`config get`

从脱敏后的配置快照中读取值（不会打印密钥）。--json 会将相同的脱敏值以 JSON 格式打印；否则字符串／数字／布尔值会直接打印，而对象／数组会以格式化后的 JSON 打印。当路径缺失时，--json 会将 { "error": "Config path not found: <path>" } 写入 stdout，并以状态码 1 退出。不使用 --json 时，诊断信息仍会输出到 stderr。

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。

包含内容

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

`config validate`

在不启动 gateway 的情况下，根据当前激活的 schema 验证当前配置。

openclaw config validate
openclaw config validate --json

如果验证已经失败，请先运行 openclaw configure 或 openclaw doctor --fix。openclaw chat 不会绕过无效配置保护。

Provider 和 runtime 的 params 包有意被类型化为 Record<string, unknown>，因为受支持的键和值由其所属方定义。openclaw config validate 可以验证容器及整体配置结构，但无法对特定 provider 的参数名称或值进行类型检查。通过验证并不能证明某个参数受支持；请查阅 provider 文档，并在选定的 runtime 和 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 '["*"]' --strict-json

config get <path> --json 会将脱敏后的值以 JSON 格式打印，而不是打印为终端格式化文本。当写入更改 agents.defaults.model 或每个代理的 agents.entries.*.model 时，OpenClaw 会在写入前通过已配置的提供方目录解析每个已更改的主模型或回退模型。未知的模型引用会被拒绝，且不会更改当前配置；运行 openclaw models list 以查看可用模型。

对象赋值默认会用目标路径替换。通常包含用户添加条目的受保护路径会拒绝会删除现有条目的替换，除非你传入 --replace：agents.defaults.models、agents.entries、models.providers、models.providers.<id>、models.providers.<id>.models、plugins.entries 和 auth.profiles。

在向这些 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` 模式

值模式
SecretRef 构建器模式
Provider 构建器模式
批量模式

openclaw config set <path> <value>

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

仅适用于 secrets.providers.<alias> 路径：

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

批量文件大小限制为 8 MiB。

不支持在运行时修改的表面不接受 SecretRef 赋值（例如 hooks.token、Discord 线程绑定 Webhook Token 以及 WhatsApp 凭据 JSON）。请参阅 SecretRef 凭据表面。

批量解析始终使用批量负载（--batch-json／--batch-file）作为真实来源；--strict-json／--json 不会改变批量解析行为。 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-source <env|file|exec|store>
--provider-timeout-ms <ms>（file、exec）

环境变量 Provider（--provider-source env）

--provider-allowlist <ENV_VAR>（可重复指定）

文件 Provider（--provider-source file）

--provider-path <path>（必需）
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>

执行 Provider（--provider-source exec）

--provider-command <path>（必需）
--provider-arg <arg>（可重复指定）
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE>（可重复指定）
--provider-pass-env <ENV_VAR>（可重复指定）
--provider-trusted-dir <path>（可重复指定）

强化版 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

`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-5.6-sol" },
      models: {
        "openai/gpt-5.6-sol": {
          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 可解析性检查，但不会写入。默认情况下，dry-run 会跳过基于 Exec 的 SecretRef；当你有意希望 dry-run 执行 provider 命令时，请添加 --allow-exec。

试运行

--dry-run 会在不写入 openclaw.json 的情况下验证更改。可用于 config set、config patch 和 config unset。

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

试运行行为

Builder 模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。
JSON 模式（--strict-json、--json 或批处理模式）：运行 schema 验证以及 SecretRef 可解析性检查。
策略验证会针对变更后的完整配置进行，因此对父对象的写入（例如将 hooks 设为对象）无法绕过不支持的作用域验证。
默认会跳过 Exec SecretRef 检查，以避免命令副作用；传入 --allow-exec 可启用（这可能会执行 provider 命令）。--allow-exec 仅在试运行时可用，且在没有 --dry-run 时会报错。

--dry-run --json 字段

ok：试运行是否通过
operations：评估的赋值次数
checks：是否运行了 schema/可解析性检查
checks.resolvabilityComplete：可解析性检查是否完整执行（跳过 exec refs 时为 false）
refsChecked：试运行期间实际解析的 ref 数量
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" | "model",
      message: string,
      ref?: string, // 可解析性错误时存在
    },
  ],
}

成功示例
失败示例

{
  "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 schema validation failed：更改后的配置结构无效；请修复路径／值或 provider／ref 对象结构。
Config policy validation failed: unsupported SecretRef usage：将该凭据改回明文／字符串输入；仅在受支持的配置项上保留 SecretRef。
SecretRef assignment(s) could not be resolved：当前无法解析所引用的 provider／ref（缺少环境变量／存储名称、文件指针无效、exec provider 失败，或 provider／source 不匹配）。
model reference validation failed：更改后的文本模型主模型或回退模型未知；运行 openclaw models list 并选择可用模型。
Dry run note: skipped <n> exec SecretRef resolvability check(s)：如果需要验证 exec 的可解析性，请使用 --allow-exec 重新运行。
对于批处理模式，请修复失败的条目，并在写入前重新运行 --dry-run。

应用更改

每次成功执行 config set / config patch / config unset 后，CLI 都会打印以下三种提示之一，以便你知道网关是否需要重启：

提示	含义
`重启网关以应用更改。`	已更改的路径需要完全重启。
`无需重启网关即可应用更改。`	热重载会自动应用更改。
`无需重启网关。`	没有影响运行时的内容发生变化。

对 plugins.entries（或其任何子路径）的写入始终需要重启，因为 CLI 无法证明每个插件的重载元数据都已加载。

写入安全

openclaw config set 和其他 OpenClaw 自有的配置写入器会在提交到磁盘之前验证整个变更后的配置。如果新负载未通过 schema 验证，或者看起来像破坏性的覆盖，活动配置会保持不变，而被拒绝的负载会以 openclaw.json.rejected.* 的形式保存在其旁边。 OpenClaw 自有的写入会将 JSON5 重新序列化为标准 JSON。当源内容包含注释时，写入器会在移除它们之前立即发出警告；如果保留注释很重要，请使用直接编辑器。

活动配置路径必须是普通文件。通过符号链接的 openclaw.json 布局不支持写入；请改用 OPENCLAW_CONFIG_PATH 直接指向真实文件。

对于小改动，优先使用 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 修复使用。插件 schema 变更或 minHostVersion 不匹配会继续报错，而不会回滚无关的用户设置，例如模型、提供方、认证配置文件、渠道、gateway 暴露、工具、内存、浏览器或 cron 配置。

修复循环

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

openclaw chat

在 TUI 中，开头带有 ! 的命令会原样运行本地 shell 命令（每个会话中首次使用时，你会先看到确认提示）：

!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，以获取迁移和修复帮助。

CLI 命令

RPC 与 API

Codex 运行框架

插件参考

插件 SDK 参考

插件维护者参考

模板

技术参考

概念内部机制

项目

贡献

配置

根选项

示例

路径

`config get`

`config file`

`config schema`

`config validate`

值

`config set` 模式

Provider 构建器标志

`config patch`

试运行

JSON 输出结构

应用更改

写入安全

修复循环

相关内容

​根选项

​示例

​路径

​config get

​config file

​config schema

​config validate

​值

​config set 模式

​Provider 构建器标志

​config patch

​试运行

​JSON 输出结构

​应用更改

​写入安全

​修复循环

​相关内容

根选项

示例

路径

`config get`

`config file`

`config schema`

`config validate`

值

`config set` 模式

Provider 构建器标志

`config patch`

试运行

JSON 输出结构

应用更改

写入安全

修复循环

相关内容