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: jq for CLI, JSON.parse/stringify for code
• YAML: yq for CLI, yaml libraries for code
• TOML: toml libraries (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.bak

Add New Keys

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

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

Remove Keys

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

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

Validation 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 -i for in-place YAML edits (preserves comments)
• Use jq with --indent to 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
EOF

Safety Rules

1. Validate syntax before saving any changes
2. Backup first - Copy original before destructive edits
3. Use tools, not manual edits - jq/yq for JSON/YAML
4. Test after changes - Load config in application context
5. Respect workspace boundaries - Only touch ~/openclaw configs
6. 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