Openclaw Config

核心功能

OpenClaw Config 是一套针对 OpenClaw Gateway 配置文件（openclaw.json / JSON5 格式）的安全编辑与验证工作流。它通过 schema-first 的方法论，帮助用户在修改 gateway.*、agents.*、models.*、channels.*、tools.*、skills.*、plugins.* 等配置键时避免类型错误和未知键，从而防止 Gateway 启动失败或安全策略意外变更。

显著优点

1. 权威 Schema 驱动：优先从运行中的 Gateway 获取实时 JSON Schema，或追溯源码级 Zod 定义，杜绝键名猜测
2. 多重编辑路径：支持 CLI 细粒度操作（config get/set/unset）、RPC 原子操作（config.patch/config.apply）以及 $include 模块化拆分
3. 严格验证闭环：每次修改后强制运行 openclaw doctor，提前拦截 .strict() 对象中的未知键错误
4. 环境变量友好：env 键支持 .catchall(z.string())，推荐将 API 密钥、Token 等敏感信息外置到环境变量而非硬编码入配置
5. 模块化配置：$include 机制支持多文件深度合并（对象递归、数组合并、原始值覆盖），便于团队分治复杂配置

潜在局限

• 版本耦合：schema 来源高度依赖 Gateway 版本，跨版本迁移需重新拉取 schema
• 自动修复风险：openclaw doctor --fix/--yes 会直接写入文件，需显式用户授权，误操作可能丢失注释或格式化
• 深度限制：$include 最大嵌套深度为 10，超复杂嵌套场景需扁平化设计
• 扩展通道宽容度：仅 channels 为 .passthrough()，其他配置区（如 agents、tools）保持严格，扩展插件自定义键仍可能触发验证失败

适合人群

• Gateway 自托管管理员与 DevOps 工程师
• 需要调试 "config validation error" 或 "Gateway refuses to start" 的排障人员
• 在 CI/CD 流水线中自动化部署 OpenClaw 配置的 SRE 团队

常规风险

• 安全降级：错误的 dmPolicy 或 allowFrom 配置可能导致未授权私信通道暴露
• 密钥泄露：将长寿命 Token 直接写入 openclaw.json 并提交到版本控制
• 服务中断：config.apply 全量替换配置时若未验证，可能导致 Gateway 重启后配置丢失或键值类型不匹配

核心用法

openclaw-config 是一套面向 OpenClaw Gateway 配置文件的 Schema-first 安全编辑工作流。用户通过 openclaw config get|set|unset 命令或 RPC 接口（config.patch/config.apply）修改配置，始终遵循「获取权威 Schema → 最小化安全变更 → 严格验证」的三步流程。

关键操作路径：

• 定位配置：按优先级解析 OPENCLAW_CONFIG_PATH → OPENCLAW_STATE_DIR/openclaw.json → ~/.openclaw/openclaw.json，支持 JSON5 格式（含注释与尾随逗号）
• 获取 Schema：运行时通过 openclaw gateway call config.schema 获取动态 Schema；离线时参考 src/config/zod-schema.ts 源码或官方文档
• 模块化配置：通过 $include 字段拆分配置至多文件，支持对象深度合并、数组拼接、原始值覆盖，最大深度 10 层并检测循环引用

显著优点

1. 防御性设计：.strict() Schema 约束阻止未知键，避免配置漂移；openclaw doctor 前置验证阻断启动失败
2. 安全优先：强制推荐环境变量/凭证文件存储 Secrets，禁止硬编码长生命周期 Token；dmPolicy="open" 等敏感配置需显式声明
3. 渐进式复杂管理：小变更用 CLI 点路径编辑，复杂场景用 $include 模块化，平衡便捷与可维护性
4. 官方生态可信：T1 来源认证，代码零网络外连、零敏感信息收集、零动态执行

潜在缺点与局限性

• 学习曲线：需理解 Zod Schema 结构、$include 合并规则及环境变量优先级，新手易在 strict 模式下触发验证错误
• 离线依赖：获取权威 Schema 依赖运行中的 Gateway 或源码访问，纯离线环境 Schema 可能版本漂移
• 严格性成本：.strict() 虽防错但也限制快速实验，扩展自定义渠道需遵循 .passthrough() 规则
• 无自动修复：--fix/--yes 需显式用户授权，批量纠错效率低于全自动工具

适合人群

• OpenClaw Gateway 运维人员与系统管理员
• 需多环境配置管理（dev/staging/prod）的开发者
• 对 AI Agent 基础设施安全性有合规要求的企业用户

常规风险

• 配置泄露：虽推荐环境变量，但 openclaw.json 仍可能误提交至版本控制，需配合 .gitignore 与预提交钩子
• 验证绕过：直接文本编辑不经过 openclaw doctor 可能引入 Schema 错误，导致 Gateway 启动失败
• 权限扩大：channels 的 .passthrough() 特性若被滥用，可能绕过安全策略开放未授权接口