OpenClaw Config

---

name: openclaw-config-master

description: Edit and validate OpenClaw Gateway config (openclaw.json / JSON5). Use when adding/changing config keys (gateway.*, agents.defaults.*, agents.list.*, channels.*, models.*, auth.*, tools.*, skills.*, plugins.*, $include) or diagnosing openclaw doctor/config validation errors, to avoid schema mismatches that prevent the Gateway from starting or weaken security policies.

---

# OpenClaw Config

一句话

用 schema-first 工作流安全编辑 OpenClaw 配置文件，验证先行，避免无效 key 导致 Gateway 无法启动或安全策略被破坏。

---

核心要点（5条）

1. **Schema 先行** — 不猜 key，从 running Gateway 或源码获取权威 schema

2. **最小修改面** — 优先用 `openclaw config set/get/unset`，不用直接编辑文件

3. **验证不可跳** — 每次改完后必须跑 `openclaw doctor`

4. **严格模式** — 大多数对象是 `.strict()`，未知 key 会导致 Gateway 拒绝启动

5. **不轻易用 --fix** — `openclaw doctor --fix/--yes` 会写文件，需用户明确同意

---

详细内容

工作流程（Safe Edit）

**1. 定位配置文件**

**2. 获取权威 schema**

- `src/config/zod-schema.ts`（根 key：`gateway`/`skills`/`plugins`）

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

- `docs/gateway/configuration.md`

**3. 应用变更**

**4. 严格验证**

---

Guardrails（避免 Schema 错误）

---

$include（模块化配置）

`$include` 在 schema 验证前解析，支持将配置分割到多个 JSON5 文件：

- 对象：递归合并

- 数组：**拼接**（不替换）

- 原始值：后者覆盖前者

---

常用配方（Common Recipes）

**设置默认 workspace**

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

**修改 Gateway 端口**

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

**分割配置文件**

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

**Telegram 开放 DMs（需显式允许发送者）**

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

**Discord Token**

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

# 方式 B：环境变量回退
# export DISCORD_BOT_TOKEN="..."

openclaw doctor

**启用 web_search**

openclaw config set tools.web.search.enabled true --json
openclaw config set tools.web.search.provider '"brave"' --json
# 建议通过环境变量提供 key
# export BRAVE_API_KEY="..."

openclaw doctor

---

复杂配置操作流程

复杂配置变更（添加新模型提供者、配置新频道等）遵循增强流程：

1. **前置检查** — 确认凭证/参数、验证平台可用性、备份配置、停止 Gateway

2. **详细配置** — 参考 `references/complex-operations.md`，遵循渐进式修改原则

3. **验证测试** — `openclaw doctor` 验证 + 逐步测试 + 准备回滚

4. **文档记录** — 记录变更、更新文档、保存版本信息

---

版本升级流程

1. **升级前准备** — 参阅 `references/version-migration.md`、创建备份、检查兼容性矩阵、查看破坏性变更

2. **执行迁移** — 使用迁移脚本、更新字段、处理废弃字段、验证完整性

3. **验证回滚** — 运行测试套件、监控行为、准备快速回滚

---

快速链接

**Channel 配置**

**复杂配置操作**

**故障诊断**

**版本升级**

---

参考资源

**快速参考**

**深度指南**

**工具脚本**