- name
- config-manager
- description
- Safe configuration file editing for JSON, YAML, TOML, and other config formats. Use when working with configuration files for: (1) Reading config values, (2) Updating/adding/removing keys, (3) Creating new config files, (4) Validating syntax, (5) Merging configs, (6) Converting between formats, or (7) Debugging config issues.
Config Manager
Handles configuration files through safe, validated operations that preserve syntax and formatting.
Core Workflows
Format Detection
Identify config format by extension:
.json→ JSON.yaml,.yml→ YAML.toml→ TOML.env→ Environment variables.ini→ INI format.xml→ XML.cfg,.conf→ Generic config
Safe Editing Rules
Golden Rule: Never manually edit structured configs unless trivial. Use tools:
- JSON:
jqfor CLI, JSON.parse/stringify for code - YAML:
yqfor CLI, yaml libraries for code - TOML:
tomllibraries (no standard CLI tool)
Common Operations
Read Values
# JSON
jq '.key' config.json
jq '.nested.key' config.json
# YAML
yq '.key' config.yaml
yq '.nested.key' config.yaml
# TOML (requires python/toml)
python -c "import toml; print(toml.load('config.toml')['key'])"Update Values
# JSON
jq '.key = "new value"' config.json > tmp && mv tmp config.json
# YAML
yq -i '.key = "new value"' config.yaml
# Always backup first
cp config.json config.json.bakAdd New Keys
# JSON
jq '.newKey = "value"' config.json > tmp && mv tmp config.json
# YAML
yq -i '.newKey = "value"' config.yamlRemove Keys
# JSON
jq 'del(.unwantedKey)' config.json > tmp && mv tmp config.json
# YAML
yq -i 'del(.unwantedKey)' config.yamlValidation Before Save
Always validate after edits:
# JSON
jq empty config.json && echo "Valid JSON"
# YAML
yamllint config.yaml || python -c "import yaml; yaml.safe_load(open('config.yaml'))"
# TOML
python -c "import toml; toml.load('config.toml')"Formatting Preservation
- Use
yq -ifor in-place YAML edits (preserves comments) - Use
jqwith--indentto control JSON spacing - Never mix tabs/spaces in YAML
- Preserve trailing newlines
Creating New Configs
Use templates or generate programmatically:
# JSON
echo '{"key": "value"}' | jq '.' > new-config.json
# YAML
cat > new-config.yaml << EOF
key: value
nested:
key2: value2
EOFSafety Rules
- Validate syntax before saving any changes
- Backup first - Copy original before destructive edits
- Use tools, not manual edits -
jq/yqfor JSON/YAML - Test after changes - Load config in application context
- Respect workspace boundaries - Only touch ~/openclaw configs
- Never commit secrets - Use .env for sensitive values, gitignore them
When to Read references/formats.md
Load when:
- Need detailed format specifications (JSON schema, YAML anchors)
- Complex merge/conflict resolution needed
- Format conversion required (JSON↔YAML↔TOML)
- Validation schemas or type checking needed