OpenClaw 配置

概述

使用基于模式（schema-first）的工作流程，安全地编辑 ~/.openclaw/openclaw.json（或由 OPENCLAW_CONFIG_PATH 设置的路径）。在修改前后进行验证，避免因无效键名或类型导致启动失败或安全行为异常。

工作流（安全编辑）

1. 确定当前生效的配置路径

• 优先级顺序：OPENCLAW_CONFIG_PATH > OPENCLAW_STATE_DIR/openclaw.json > ~/.openclaw/openclaw.json
• 配置文件为 JSON5 格式（支持注释和尾随逗号）

1. 获取权威的模式定义（不要猜测字段）

• 若网关正在运行：使用命令 openclaw gateway call config.schema --params '{}' 获取与当前版本匹配的 JSON Schema。
• 否则：参考 openclaw/openclaw 项目源码中的权威定义，主要包括：

- src/config/zod-schema.ts（OpenClawSchema 的根级键，如 gateway/skills/plugins）

- src/config/zod-schema.*.ts（子模块：channels/providers/models/agents/tools）

- docs/gateway/configuration.md（仓库文档 + 示例）

1. 以最小风险范围应用变更

• 优先采用小规模修改：使用 openclaw config get|set|unset（支持点号路径或方括号表示法）。
• 若网关在线且希望“写入 + 验证 + 重启”一步完成：可使用 RPC 接口 config.patch（合并补丁）或 config.apply（替换整个配置；需谨慎使用）。
• 对于复杂配置，建议使用 $include 分割配置（见下文）。

1. 严格验证

• 执行 openclaw doctor，根据报告的 path 和 message 修复问题。
• 未经用户明确同意，不要使用 openclaw doctor --fix/--yes（该命令会直接写入配置或状态文件）。

安全约束（避免模式错误）

• 大多数对象为严格模式（.strict()）：未知键通常会导致验证失败，网关将拒绝启动。
• channels 为 .passthrough()：扩展频道（如 matrix/zalo/nostr 等）可添加自定义键，但多数提供方配置仍保持严格。
• env 为 .catchall(z.string())：可在 env 下直接放置字符串环境变量，也可使用 env.vars。
• 敏感信息：优先使用环境变量或凭证文件。避免将长期有效的令牌/API 密钥写入 openclaw.json。

$include（模块化配置）

$include 在模式验证前解析，允许将配置拆分到多个 JSON5 文件中：

• 支持格式："$include": "./base.json5" 或 "$include": ["./a.json5", "./b.json5"]
• 相对路径相对于当前配置文件所在目录解析。
• 深度合并规则（按实现方式）：

- 对象：递归合并

- 数组：拼接（不覆盖）

- 原始值：后出现的值优先

• 若同级存在其他键，其值会覆盖被包含文件中的相同键。
• 限制：最大嵌套深度为 10；检测到循环包含时将拒绝加载。

常用操作示例

1. 设置默认工作区

openclaw config set agents.defaults.workspace '"~/.openclaw/workspace"' --json
openclaw doctor

1. 修改网关端口

openclaw config set gateway.port 18789 --json
openclaw doctor

1. 拆分配置（示例）

// ~/.openclaw/openclaw.json
{
  "$include": ["./gateway.json5", "./channels/telegram.json5"],
}

1. Telegram 开启私聊（必须显式允许发送者）

模式约束：当 dmPolicy="open" 时，allowFrom 必须包含 "*"

openclaw config set channels.telegram.dmPolicy '"open"' --json
openclaw config set channels.telegram.allowFrom '["*"]' --json
openclaw doctor

1. Discord 机器人令牌（配置或环境变量回退）

# 方式 A：写入配置
openclaw config set channels.discord.token '"YOUR_DISCORD_BOT_TOKEN"' --json

# 方式 B：通过环境变量回退（仍建议保留 channels.discord 配置项）
# export DISCORD_BOT_TOKEN="..."

openclaw doctor

1. 启用 web_search（Brave / Perplexity）

openclaw config set tools.web.search.enabled true --json
openclaw config set tools.web.search.provider '"brave"' --json

# 推荐：通过环境变量提供密钥（或写入 tools.web.search.apiKey）
# export BRAVE_API_KEY="..."

openclaw doctor

资源参考

需要查找字段索引或来源位置时可参考以下文件：

• references/openclaw-config-fields.md（根级键索引 + 字段列表及来源）
• references/schema-sources.md（如何在 openclaw 仓库中定位模式与约束）
• scripts/openclaw-config-check.sh（打印配置路径并执行 doctor 检查）