USER MANUAL · INSIGHTS

Config Versions

Track, compare, and safely rollback agent configuration changes.

/config

Overview#

Config Versions is ClawButler's configuration safety system. Every time an agent's configuration is synced from OpenClaw, ClawButler automatically captures a snapshot. These snapshots form a versioned timeline that lets you see exactly what changed, when, and whether the change introduces risk.

The system supports semantic diff (field-level comparison categorized by domain), risk classification (redline and yellowline fields), drift detection (runtime vs stored config comparison), and rollback with dry-run preview. Together, these capabilities give you confidence that configuration changes across your agent fleet are intentional, auditable, and reversible.

Prerequisites#

Prerequisites

At least one connector configured and synced (see Connectors)
Agents discovered and visible in the Agents page

OpenClaw Configuration#

Agent configuration is read from the OpenClaw gateway via the config.get RPC method. ClawButler uses the 'resolved' view, which includes all defaults merged into each agent's config entry. This ensures you see the complete effective configuration, not just user-level overrides.

The resolved config includes agent identity, model settings (primary and fallbacks), tools, skills, channels, cron jobs, and dependencies. Changes made directly in OpenClaw's config YAML are picked up on the next sync cycle.

Tip

ClawButler always reads the 'resolved' config (defaults merged), not the raw 'config' view. This means agents inheriting from agents.defaults will show their full effective configuration, even if the individual agent entry in the YAML is minimal.

ClawButler Configuration#

Config snapshots are managed automatically. Key behaviors:

-Auto-snapshot: A new config version is captured on every connector sync. No manual action needed.
-Scope tracking: Each snapshot records one of 4 scopes — agent_config, workspace_bundle, bindings, or dependency_meta — so you can filter changes by category.
-Trust baseline: You can manually set any version as the trust baseline (a known-good reference point) for comparison via TCC Step 02.

Expected Results#

After syncing, the Config Versions page provides:

-Version timeline: A chronological list of config snapshots per agent, with timestamps, scope labels, and version IDs
-Semantic diff view: Field-by-field comparison between any two versions, with changes categorized as identity, model, tools, skills, bindings, or dependencies
-Risk indicators: Fields classified as redline (critical — e.g., permissions, allowed_tools, security_policy, api_keys) or yellowline (high — e.g., model, temperature, system_prompt) are highlighted in diffs
-Drift alerts: When a drift check detects differences between the runtime config and the stored snapshot, affected fields are flagged with noise filtering applied (runtime-only fields like timestamps and cache stats are excluded)

Web Operations#

Navigate to Config Versions from the Insights section in the sidebar. Select an agent to view its configuration history.

Version History

Select an agent from the dropdown, then choose a scope (agent_config, workspace_bundle, bindings, or dependency_meta) to filter the timeline. Each entry shows the version ID, timestamp, and scope. Click any version to view its full snapshot.

Semantic Diff

Select two versions from the timeline to compare them. The diff view categorizes changes into domains: identity, model, tools, skills, bindings, and dependencies. Each field is labeled as added, removed, or modified. Redline fields (permissions, security_policy, api_keys, etc.) and yellowline fields (model, temperature, system_prompt, etc.) are visually highlighted.

Drift Detection

Click the drift check button to compare the agent's current runtime config (fetched live from OpenClaw) against the latest stored snapshot. The comparison applies noise filtering to exclude runtime-only fields (timestamps, cache statistics, ephemeral state) that change without user action. Only meaningful differences are reported.

Rollback

Select a target version and click Rollback. A dry-run preview shows exactly what will change before you confirm. On confirmation, ClawButler applies the snapshot and verifies the result via hash comparison against the OpenClaw gateway to ensure the rollback was applied correctly.

Trust Baseline

Mark any version as the trust baseline — a known-good reference configuration. Future diffs can be compared against this baseline to detect unintended deviation. This is part of TCC (Trusted Change Control) Step 02.

CLI Operations#

List all config versions for an agent, ordered by timestamp

Terminal

$ ap config versions <agent_id>

Show a semantic diff between two config versions

Terminal

$ ap config diff <agent_id> --v1 <id1> --v2 <id2>

Check for config drift between runtime and stored config

Terminal

$ ap config drift-check <agent_id>

Preview a rollback (dry-run mode does not apply changes)

Terminal

$ ap config rollback <agent_id> --version <id> --dry-run

Set the current config as the trust baseline

Terminal

$ ap config baseline <agent_id> --set

Mobile Operations#

On mobile, config history is available within the agent detail screen. Navigate to an agent from the Agents tab and scroll to the Config History section.

-Chronological list of config versions with scope and timestamp
-Tap any version to view its full snapshot contents
-Pull-to-refresh to check for new versions after a sync

FAQ#

Q: What triggers a new config snapshot?

A: A new snapshot is captured automatically every time a connector sync runs. This includes scheduled syncs and manual 'Sync Agents' actions. If the configuration hasn't changed since the last snapshot, a new version is still recorded to maintain a complete timeline.

Q: What are redline vs yellowline fields?

A: Redline fields are critical security-sensitive settings: permissions, allowed_tools, blocked_tools, security_policy, max_cost_per_call, kill_switch, api_keys, secrets, and auth_config. Changes to these require extra scrutiny. Yellowline fields are high-impact operational settings: model, temperature, max_tokens, system_prompt, and skills. Changes here affect agent behavior but are not direct security risks.

Q: Can I rollback to any version?

A: Yes. You can rollback to any previously captured snapshot. The dry-run preview shows all fields that will change before you confirm. After rollback, ClawButler verifies the result via hash comparison with the OpenClaw gateway to confirm the rollback was applied correctly.