古法编程

Appearance

openclaw config 提供 get/set/patch/unset/file/schema/validate 等子命令，用于在不启动 Gateway 时修改 openclaw.json。支持 JSON5 值、SecretRef 构建器、provider 构建器和批量模式；使用 --dry-run 预演验证，写前校验 schema；Nix 模式下只读。常用命令：openclaw config validate 检查配置合法性、openclaw config file 查看当前配置文件路径。

openclaw config - OpenClaw 配置命令参考 ​

非交互式编辑 openclaw.json 的配置助手，支持 get/set/patch/unset/file/schema/validate 操作，可通过路径读写任意配置项并打印当前配置文件路径。不带子命令直接运行时，会打开配置向导（等同于 openclaw configure）。

TIP

当 OPENCLAW_NIX_MODE=1 时，OpenClaw 将 openclaw.json 视为不可变文件。只读命令（config get、config file、config schema、config validate）仍可使用，但写入命令会被拒绝。智能体应编辑 Nix 源安装配置，对于官方 nix-openclaw 发行版，请参考 nix-openclaw Quick Start 并在 programs.openclaw.config 或 instances.<name>.config 下设置值。

示例 ​

bash
openclaw config file
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 Schema 打印到标准输出。用于编辑器工具、Control UI 文档元数据、通配符/数组项节点、插件和渠道 schema 的实时合并。

bash
openclaw config schema

可导出到文件：

bash
openclaw config schema > openclaw.schema.json
Schema 包含的内容
  • 当前根配置 schema，以及用于编辑器工具的 $schema 字符串字段。
  • Control UI 使用的 title 和 description 文档元数据。
  • 当匹配字段文档存在时，嵌套对象、通配符 (*) 和数组项 ([]) 节点继承相同的 title/description 元数据。
  • anyOf/oneOf/allOf 分支在匹配文档时也继承元数据。
  • 当运行时清单可加载时，尽力合并插件和渠道 schema 元数据。
  • 即使当前配置无效，也提供一个干净的 fallback schema。
相关运行时 RPC

config.schema.lookup 返回单条标准化配置路径及其浅层 schema 节点（title, description, type, enum, const, 常见边界）、匹配的 UI 提示元数据以及直接子节点摘要。用于 Control UI 或自定义客户端中的路径级向下钻取。

路径格式 ​

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

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

用 agents 列表的索引定位具体的 agent：

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

值解析 ​

值会优先按 JSON5 解析，失败时作为字符串处理。使用 --strict-json 强制要求 JSON5 解析。--json 作为旧版别名仍然支持。

bash
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 格式），而非终端美化格式。

WARNING

对象赋值默认会替换目标路径。对于经常包含用户添加条目的受保护 map/list 路径（如 agents.defaults.models、models.providers、models.providers.<id>.models、plugins.entries、auth.profiles），如果不传递 --replace，则拒绝会移除现有条目的替换操作。

使用 --merge 向这些 map 添加条目：

bash
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 支持四种写入方式：

值模式 ​

bash
openclaw config set <path> <value>

SecretRef 构建器模式 ​

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

Provider 构建器模式 ​

仅限 secrets.providers.&lt;alias&gt; 路径：

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

批量模式 ​

bash
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" }
  }
]'
bash
openclaw config set --batch-file ./config-set.batch.json --dry-run

批量解析始终以批量载荷（--batch-json/--batch-file）为准，--strict-json/--json 不影响批量解析行为。

WARNING

SecretRef 赋值不能在运行时可变表面（例如 hooks.token、commands.ownerDisplaySecret、Discord 线程绑定 webhook token、WhatsApp creds JSON）上使用。详见 SecretRef 凭据支持面。

JSON 路径/值模式对 SecretRef 和 provider 同样适用：

bash
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.&lt;alias&gt;。

通用标志
  • --provider-source <env|file|exec>
  • --provider-timeout-ms &lt;ms&gt;（file、exec）
Env provider（--provider-source env）
  • --provider-allowlist <ENV_VAR>（可重复）
File provider（--provider-source file）
  • --provider-path &lt;path&gt;（必填）
  • --provider-mode <singleValue|json>
  • --provider-max-bytes &lt;bytes&gt;
  • --provider-allow-insecure-path
Exec provider（--provider-source exec）
  • --provider-command &lt;path&gt;（必填）
  • --provider-arg &lt;arg&gt;（可重复）
  • --provider-no-output-timeout-ms &lt;ms&gt;
  • --provider-max-output-bytes &lt;bytes&gt;
  • --provider-json-only
  • --provider-env <KEY=VALUE>（可重复）
  • --provider-pass-env <ENV_VAR>（可重复）
  • --provider-trusted-dir &lt;path&gt;（可重复）
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command

加固版 exec provider 示例：

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-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

Dry run（预演模式） ​

使用 --dry-run 可以验证改动而不实际写入 openclaw.json。

bash
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 行为说明
  • 构建器模式：对变更的 ref/provider 执行 SecretRef 可解析性检查。
  • JSON 模式（--strict-json、--json 或批量模式）：执行 schema 验证 + SecretRef 可解析性检查。
  • 策略验证也会对已知不支持的 SecretRef 目标表面进行检查。
  • 策略检查评估完整的修改后配置，因此父对象写入（例如将 hooks 写为一个对象）不能绕过不支持的表面验证。
  • exec SecretRef 检查默认跳过，以避免命令副作用。
  • 使用 --allow-exec 加上 --dry-run 可开启 exec SecretRef 检查（此时可能实际执行 provider 命令）。
  • --allow-exec 仅在 dry-run 下有效，单独使用会报错。
--dry-run --json 字段

--dry-run --json 输出机器可读报告，包含以下字段：

  • ok：dry-run 是否通过
  • operations：评估的赋值数量
  • checks：schema/可解析性检查是否执行
  • checks.resolvabilityComplete：可解析性检查是否全部完成（跳过 exec ref 时为 false）
  • refsChecked：dry-run 期间实际解析的 ref 数量
  • skippedExecRefs：因未设置 --allow-exec 而跳过的 exec ref 数量
  • errors：当 ok=false 时返回的 schema/可解析性错误结构

JSON 输出结构 ​

json5
{
  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, // 可解析性错误时存在
    },
  ],
}

成功示例：

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

失败示例：

json
{
  "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"
    }
  ]
}
dry-run 失败时的常见错误
  • 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 不匹配）。
  • Dry run note: skipped &lt;n&gt; exec SecretRef resolvability check(s)：跳过了 exec ref 检查，如需验证请加 --allow-exec 重跑。
  • 批量模式下，修复失败条目后重跑 --dry-run 再正式写入。

config patch ​

config patch 用于一次性应用一个配置文件形状的补丁，而不是多次运行 config set。补丁输入为 JSON5 对象。对象递归合并，数组和标量替换目标值，null 删除目标路径。

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

也可通过 stdin 管道传递补丁，便于远程设置脚本：

bash
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

示例补丁文件：

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 &lt;path&gt;：

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

--dry-run 运行 schema 和 SecretRef 可解析性检查，但不写入。默认跳过 exec 提供的 SecretRef 检查；使用 --allow-exec 时 dry-run 会执行 provider 命令。

子命令：config file ​

打印当前配置文件的路径（从 OPENCLAW_CONFIG_PATH 或默认位置解析）。该路径应指向一个普通文件，而不是符号链接。

bash
openclaw config file

编辑配置后需重启 Gateway 才能生效。

config validate ​

在不启动 Gateway 的情况下，根据当前 schema 验证配置是否合法。

bash
openclaw config validate
openclaw config validate --json

写入安全（Write safety） ​

openclaw config set 及其他 OpenClaw 写入命令在提交到磁盘前会完整验证修改后的配置。如果新载荷未通过 schema 验证或看起来具有破坏性覆盖，则不会修改当前配置，并将被拒绝的载荷保存在 openclaw.json.rejected.* 文件中。

WARNING

当前配置路径必须是普通文件。不支持符号链接的 openclaw.json 写入；使用 OPENCLAW_CONFIG_PATH 直接指向真实文件。

对于小型编辑，推荐使用 CLI 写入：

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

如果写入被拒绝，检查保存的载荷并修正完整配置：

bash
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 不一致会保持报错，而不会回滚无关的用户设置（如 models、providers、auth profiles、channels、gateway exposure、tools、memory、browser、cron）。

典型修复循环 ​

  1. 与文档对比：让智能体将你的当前配置与相关文档页进行比较，并给出最小修复方案。
  2. 应用目标编辑：用 openclaw config set 或 openclaw configure 进行编辑。
  3. 重新验证：每次修改后运行 openclaw config validate。
  4. 修复运行时问题：如果验证通过但运行时仍然不健康，运行 openclaw doctor 或 openclaw doctor --fix 进行迁移和修复。
bash
openclaw chat

在 TUI 内可执行：

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

TIP

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

相关文档 ​

常见问题 ​

如何在不打开交互界面的情况下修改 openclaw.json？ ​

使用 openclaw config set &lt;path&gt; &lt;value&gt; 直接写入，支持 JSON5 值、SecretRef 构建器、provider 构建器。如果想批量修改，可以使用 openclaw config patch --file patch.json5 一次性应用多个变更。修改后运行 openclaw config validate 检查合法性，然后重启 Gateway。

什么情况下 dry-run 会失败？ ​

常见原因：路径不合法、值类型错误、SecretRef 引用不能解析（环境变量未设置、文件路径无效）、在不受支持的表面使用了 SecretRef（如 hooks.token）。查看 --dry-run --json 输出的 errors 数组获取具体 kind 和 message。exec 类的 SecretRef 默认跳过，需添加 --allow-exec 才能校验。

为什么我执行 openclaw config set 后配置没变？ ​

可能是写入安全保护拦截了变更。检查当前目录下是否有 openclaw.json.rejected.* 文件，查看被拒绝的载荷和原因。常见原因：schema 验证失败、尝试使用 --merge 覆盖受保护路径但未加 --merge、或者在 Nix 模式下配置被视为不可变。运行 openclaw config validate 确认当前配置是否异常。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策