OpenClaw 配置

概述

安全地编辑~/.openclaw/openclaw.json（或由OPENCLAW_CONFIG_PATH环境变量设置的路径），请采用模式优先的工作流程。在更改前后进行验证，以避免因无效的键或类型导致启动失败或改变安全行为。

工作流程（安全编辑）

1. 确定活动配置文件的路径

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

2. 获取权威的模式定义（不要猜测键名）

• 如果网关正在运行：使用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(仓库文档 + 示例)

3. 以最小的安全影响范围应用更改

• 优先进行小范围编辑：openclaw config get|set|unset(点路径或括号表示法)。
• 如果Gateway在线，并且您希望“写入 + 验证 + 重启”一步完成：使用RPCconfig.patch（合并补丁）或config.apply（替换整个配置；请谨慎使用）。
• 对于复杂配置，请使用$include拆分配置（见下文）。

4. 严格验证

• 运行openclaw doctor，然后根据报告的路径+消息修复问题。
• 未经用户明确同意，请勿运行openclaw doctor --fix/--yes（它会写入配置/状态文件）。

防护机制（避免模式错误）

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

$include（模块化配置）

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

• 支持"$include": "./base.json5"或"$include": ["./a.json5", "./b.json5"]
• 相对路径是基于当前配置文件所在的目录进行解析的。
• 深度合并规则（按实现方式）：
  • 对象：递归合并
  • 数组：连接（非替换）
  • 基本类型：后出现的值覆盖前者
• 如果存在同级键与$include并列，
• 则同级键的值会覆盖被包含文件中的值。

限制：最大深度为10；会检测并拒绝循环包含。

1. 常用配置示例

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

2. 设置默认工作区

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

3. 更改网关端口

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

4. 拆分配置（示例）

Telegram开放私信（必须明确允许发送者）模式约束：当dmPolicy="open"时，allowFrom必须包含"*"

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

5. Discord令牌（配置文件或环境变量回退）

# Option A: write to config
openclaw config set channels.discord.token '"YOUR_DISCORD_BOT_TOKEN"' --json

# Option B: env var fallback (still recommend a channels.discord section exists)
# export DISCORD_BOT_TOKEN="..."

openclaw doctor

6. 启用网络搜索（Brave / Perplexity）

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

# Recommended: provide the key via env var (or write 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（打印配置路径 + 运行诊断程序）