配置管理器

通过安全、经过验证的操作处理配置文件，确保语法和格式的完整性。

核心工作流程

格式检测

根据文件扩展名识别配置格式：

• .json → JSON
• .yaml, .yml → YAML
• .toml → TOML
• .env → 环境变量
• .ini → INI 格式
• .xml → XML
• .cfg, .conf → 通用配置

安全编辑规则

黄金法则： 除非是简单修改，否则不要手动编辑结构化配置。应使用工具：

• JSON：命令行使用 jq，代码中使用 JSON.parse/stringify
• YAML：命令行使用 yq，代码中使用 yaml 库
• TOML：使用 toml 库（无标准命令行工具）

常用操作

读取值

# JSON
jq '.key' config.json
jq '.nested.key' config.json

# YAML
yq '.key' config.yaml
yq '.nested.key' config.yaml

# TOML（需 Python 和 toml 库）
python -c "import toml; print(toml.load('config.toml')['key'])"

更新值

# JSON
jq '.key = "new value"' config.json > tmp && mv tmp config.json

# YAML
yq -i '.key = "new value"' config.yaml

# 操作前始终备份
cp config.json config.json.bak

添加新键

# JSON
jq '.newKey = "value"' config.json > tmp && mv tmp config.json

# YAML
yq -i '.newKey = "value"' config.yaml

删除键

# JSON
jq 'del(.unwantedKey)' config.json > tmp && mv tmp config.json

# YAML
yq -i 'del(.unwantedKey)' config.yaml

保存前的验证

修改后必须进行验证：

# JSON
jq empty config.json && echo "有效 JSON"

# YAML
yamllint config.yaml || python -c "import yaml; yaml.safe_load(open('config.yaml'))"

# TOML
python -c "import toml; toml.load('config.toml')"

格式保留策略

• 使用 yq -i 进行原地 YAML 编辑（保留注释）
• 使用 jq --indent 控制 JSON 的缩进
• YAML 中禁止混用制表符和空格
• 保持结尾换行符

创建新配置文件

建议使用模板或程序生成：

# JSON
echo '{"key": "value"}' | jq '.' > new-config.json

# YAML
cat > new-config.yaml << EOF
key: value
nested:
  key2: value2
EOF

安全规范

1. 验证语法：保存任何更改前必须验证格式
2. 先备份：执行破坏性操作前复制原始文件
3. 使用工具：避免手动编辑，使用 jq / yq 处理 JSON/YAML
4. 变更后测试：在应用环境中加载配置以验证有效性
5. 遵守工作区边界：仅操作 ~/openclaw 目录下的配置
6. 不提交敏感信息：敏感值使用 .env 文件管理，并加入 .gitignore

何时查阅 references/formats.md

当需要以下内容时请参考该文档：

• 详细的格式规范（如 JSON Schema、YAML 锚点）
• 复杂的合并或冲突解决
• 格式转换需求（JSON ↔ YAML ↔ TOML）
• 验证模式或类型检查