OpenClaw openclaw.json 全量解析：配置封神攻略
玩OpenClaw被openclaw.json逼疯？核心精髓全浓缩在这一个配置文件里。摸透每个配置项，让你彻底和启动报错、运行卡顿说再见。
四个核心基础规则
1. 文件路径与格式
| 项目 | 说明 |
|---|
| 默认路径 | ~/.openclaw/openclaw.json |
| 格式 | JSON5（支持注释和尾逗号） |
| 自定义路径 | 通过 OPENCLAW_CONFIG_PATH 环境变量 |
2. 严格Schema校验
| 规则 | 说明 |
|---|
| 未知字段 | 网关拒绝启动 |
| 类型错误 | 网关拒绝启动 |
| 枚举值无效 | 网关拒绝启动 |
| 唯一例外 | 根级 $schema（给IDE做联想） |
诊断命令：openclaw doctor 快速诊断修复配置问题。
3. 四种编辑方式
| 方式 | 适合人群 |
|---|
交互向导 openclaw onboard/configure | 新手，输入自动校验 |
CLI命令 openclaw config set/get/unset | 写脚本 |
Control UI 127.0.0.1:18789 | 可视化操作 |
| 文本编辑器 | 高级玩家，版本管理 |
4. 热加载机制
| 模块 | 是否热更新 |
|---|
| channels | ✅ 改完即生效 |
| agents | ✅ 改完即生效 |
| models | ✅ 改完即生效 |
| 网关栈 | ❌ 需重启 |
| plugins | ❌ 需重启 |
默认hybrid模式：能热更新的自动生效，需重启的会提示。
顶层配置结构（按重要性排序）
高频配置
| 配置项 | 说明 |
|---|
| models | 模型配置（最核心） |
| channels | 渠道配置（飞书/钉钉/微信） |
| agents | Agent列表和配置 |
| llm | 默认LLM配置 |
中高频配置
| 配置项 | 说明 |
|---|
| skills | Skill配置 |
| memory | 记忆配置 |
| heartbeat | 心跳配置 |
| security | 安全配置 |
低频配置
| 配置项 | 说明 |
|---|
| plugins | 插件配置 |
| gateway | 网关栈配置 |
| logging | 日志配置 |
常见配置问题
| 问题 | 原因 | 解决方案 |
|---|
| 网关启动失败 | 配置字段错误 | openclaw doctor 诊断 |
| 消息收不到 | channels配置有误 | 检查webhook和secret |
| 权限不对 | security未配置 | 配置权限分级 |
| 改了不生效 | 非热更新模块 | 重启网关 |
安全配置要点
| 要点 | 说明 |
|---|
| master_key | 设置主密钥 |
| 权限分级 | 低/中/高风险操作分级 |
| AGENTS.md安全 | 防止被恶意写入 |
| 定期检查 | 检查配置文件变更 |
总结
| 要点 | 说明 |
|---|
| 基础规则 | JSON5格式 + 严格校验 + 热加载 |
| 编辑方式 | 交互向导/CLI/UI/编辑器 |
| 核心配置 | models > channels > agents > llm |
| 安全 | master_key + 权限分级 |
一句话总结：把OpenClaw配置当工程来维护，稳定性、安全性、成本都能显著提升。
