Agent Config Sync (v1.2)

Keep configuration consistent across multiple OpenClaw agents using version tracking, CHANGELOG-based change detection, and automatic sync dispatch with journal-backed two-phase commit.

New in v1.2: Scripts now read agent list from agent-registry.json (single source of truth). Bilingual output (--lang en|zh). --dry-run and --demo modes. See Upgrading for v1.1 → v1.2 migration.

Security: This skill writes to agent workspaces across your OpenClaw deployment. Read the full SECURITY.md for permission scope, path validation, cross-agent isolation, and user consent flow. Key highlights:

• All scripts require --confirm for write operations (use --dry-run to preview first)
• Only paths under ~/.openclaw/workspace-* are allowed (path validation enforced)
• Each agent can only read/write its own workspace files
• No network access, no external API calls, no credential access

⚙️ Customization Variables

Edit references/agent-registry.json — this is the only file you need to change for your deployment:

Example — after customization for user "Alice" with agents alice-dev, alice-biz, alice-ops:

{
  "vars": {
    "workspace_root": "~/.openclaw",
    "master_agent": "alice-ops",
    "master_memory": "${vars.workspace_root}/workspace-${vars.master_agent}/memory"
  },
  "agents": {
    "alice-dev": { "name": "Alice Dev", "role": "Development",
      "workspace": "${vars.workspace_root}/workspace-alice-dev" },
    "alice-biz": { "name": "Alice Biz", "role": "Business",
      "workspace": "${vars.workspace_root}/workspace-alice-biz" },
    "alice-ops": { "name": "Alice Ops", "role": "Coordination",
      "workspace": "${vars.workspace_root}/workspace-alice-ops" }
  }
}

Scripts resolve ${vars.xxx} placeholders at runtime — no hardcoded paths.

Overview

Architecture

┌─ Version Tracking ──────────────────────┐
│  .current_system_version  (monotonic)    │
│  .last_sync_version       (last synced)  │
│  CHANGELOG.md             (structured)   │
│  .sync_journal.jsonl      (atomicity)    │
└──────────────────────────────────────────┘
         │ version mismatch detected by HEARTBEAT
         ▼
┌─ Sync Journal (two-phase commit) ────────┐
│  PREPARE → journal entry written          │
│  DISPATCH → sessions_send / pending_sync  │
│  COMMIT → mark done or retry later        │
└──────────────────────────────────────────┘
         │ each agent processes independently
         ▼
┌─ Agent Side ────────────────────────────┐
│  BOOTSTRAP.md → ls pending_sync_*.md    │
│  HEARTBEAT.md → check + verify SHA256   │
│  SYNC.md → manual sync instructions     │
└──────────────────────────────────────────┘

What it syncs

Installation

Prerequisites

• OpenClaw with 2+ agents
• One designated "master" coordination agent
• clawhub CLI installed

Step 1: Install the Skill

clawhub install agent-config-sync

Step 2: Customize Agent Registry

Edit ~/.openclaw/skills/agent-config-sync/references/agent-registry.json:

1. Change vars.master_agent to your coordination agent's ID
2. Replace the agents entries with your own agents
3. Adjust vars.workspace_root if your OpenClaw workspace is not ~/.openclaw

See the Customization Variables table above, or the English quickstart at references/quickstart.md.

Step 3: Initialize Sync Infrastructure

cd ~/.openclaw/skills/agent-config-sync

# Preview what will be created (safe, no changes required)
bash scripts/init_sync.sh --dry-run

# Run the real setup (--confirm required for write operations)
bash scripts/init_sync.sh --confirm

⚠️ Safety: --confirm is required for any write operation. Without it, the script exits with a prompt explaining how to preview with --dry-run first. --dry-run mode does not need --confirm.

This creates:

• Version sentinel files (.current_system_version, .last_sync_version) in master's memory/
• CHANGELOG.md with structured format
• .sync_journal.jsonl for sync atomicity
• SYNC.md, bootstrapped BOOTSTRAP.md, and HEARTBEAT.md sync checks in each agent workspace

Step 4: Add HEARTBEAT Item to Master Agent

Copy the HEARTBEAT item from references/sync-setup.md into your master agent's HEARTBEAT.md. This is item 12 — the heartbeat check that detects version mismatches and dispatches syncs.

Step 5: Verify Setup

# Check version files
cat ~/.openclaw/workspace-\x3Cmaster>/memory/.current_system_version  # should be v1.0

# Check agent sync files
ls ~/.openclaw/workspace-*/SYNC.md

Configuration

Agent Registry (references/agent-registry.json)

The single source of truth. Fields:

CHANGELOG Format

All version entries must follow the structured format defined in references/sync-setup.md:

## vX.Y (YYYY-MM-DD)
**Change Type**: \x3Ccategory>
**Affected Agents**: \x3Cwhich agents>
**Author**: \x3Cwho made the change>
**Priority**: normal | high | critical

### Added / Changed / Deprecated
- \x3Cdescription>

Language

Scripts support --lang en and --lang zh (default). Use --lang en for English output:

bash scripts/init_sync.sh --lang en
bash scripts/force_sync.sh --lang en ~/memory v1.0 v1.1

Usage Scenarios

Scenario A: Adding a new model to all agents

Situation: You want all agents to switch to a new default model.

1. Update CHANGELOG.md in master's memory directory:

   ## v3.2 (2026-05-16)
   **Change Type**: ⚙️ OpenClaw Config
   **Affected Agents**: all
   **Author**: AMaster
   **Priority**: high
   
   ### Changed
   - Default model switched to deepseek-v4-pro for all agents
   - Fallback model set to deepseek-v3
   

2. Bump the version:

   echo "v3.2" > memory/.current_system_version
   

3. Next HEARTBEAT (every 5 min): version mismatch detected → dispatches to all agents. Agents update their model configs accordingly.

4. Agents delete their pending_sync_v3.2_\x3Csha>.md after applying.

Scenario B: Coordinated code deployment

Situation: You fix a bug in shared code used by multiple agents.

1. Fix the bug, tell the master agent to record the change.

2. Master updates CHANGELOG.md with the version entry, bumps .current_system_version.

3. HEARTBEAT dispatches. Online agents receive via sessions_send; offline agents get pending_sync files.

4. All agents verify version before running the shared system.

Daily Operations

Recording a Change

Whenever a config or system change affects multiple agents:

1. Edit CHANGELOG.md in master's memory/ directory — add a new ## vX.Y section
2. Bump the version — echo "vX.Y" > memory/.current_system_version
3. The change is dispatched automatically on the next master heartbeat

Force-Syncing Immediately

cd ~/.openclaw/skills/agent-config-sync

# Preview the version change
bash scripts/force_sync.sh --dry-run ~/.openclaw/workspace-\x3Cmaster>/memory v3.0 v3.1

# Execute (--confirm required for write operations)
bash scripts/force_sync.sh --confirm ~/.openclaw/workspace-\x3Cmaster>/memory v3.0 v3.1

After running, the next heartbeat detects current (v3.1) != last_sync (v3.0) and dispatches.

Checking Sync Status

# Check version sentinel files
cat ~/.openclaw/workspace-\x3Cmaster>/memory/.current_system_version
cat ~/.openclaw/workspace-\x3Cmaster>/memory/.last_sync_version

# Check journal for recent sync records
tail -5 ~/.openclaw/workspace-\x3Cmaster>/memory/.sync_journal.jsonl

# Check for pending syncs on an agent
ls ~/.openclaw/workspace-\x3Cagent>/pending_sync_*.md

Demo Mode (Learning)

cd ~/.openclaw/skills/agent-config-sync
bash scripts/init_sync.sh --demo --lang en

Creates a complete demo deployment in /tmp/ showing the full file structure without touching real workspaces.

Manual Sync Trigger

bash skills/agent-config-sync/scripts/force_sync.sh \
  ~/.openclaw/workspace-amaster/memory v3.0 v3.1

This creates a version mismatch (old=3.0, new=3.1) — next heartbeat dispatches.

Troubleshooting

Agents Not Receiving Updates

Version Conflicts

Journal Issues

Rolling Back a Change

To undo a sync that was dispatched but shouldn't have been:

1. Revert the version: echo "v3.0" > memory/.current_system_version (back to previous)
2. Revert the last_sync: echo "v3.0" > memory/.last_sync_version
3. Mark the journal record: Edit .sync_journal.jsonl, find the record with "to":"v3.1" and change status to "reverted"
4. Notify agents: Agents check pending_sync files on heartbeat — delete old ones
5. Verify: ls ~/.openclaw/workspace-*/pending_sync_*.md should be empty

Alternatively, use force_sync.sh in "reverse":

bash scripts/force_sync.sh memory/ v3.0 v3.1   # created mismatch forward
bash scripts/force_sync.sh memory/ v3.1 v3.0   # reverse: current=v3.0, last=v3.1 → no dispatch (current \x3C last)

⚠️ force_sync.sh only creates the version mismatch — actual rollback requires reverting the changes in CHANGELOG and agent configs manually.

🌐 Internationalization

This skill supports both Chinese and English environments:

Using English:

# Install and initialize in English
bash scripts/init_sync.sh --lang en

# Demo in English
bash scripts/init_sync.sh --lang en --demo

New English-speaking users should start with references/quickstart.md.

Upgrading

From v1.0 to v1.1

• agent-registry.json introduced (previously agent list was hardcoded)
• pending_sync files now use version-named format (pending_sync_v3.1_a1b2c3.md) instead of single pending_sync.md
• Journal-based two-phase commit added
• No breaking changes — existing sentinel files and CHANGELOG format unchanged

From v1.1 to v1.2

• Registry is now single source of truth: scripts read agent list from agent-registry.json instead of command-line args
• Bilingual scripts: --lang en|zh flag on both init_sync.sh and force_sync.sh
• New flags: --dry-run (preview), --demo (learning mode), --help
• English quickstart: references/quickstart.md added
• agent-registry.json format changed: added vars section with placeholders

Migration steps (v1.1 → v1.2)

1. Update agent-registry.json:

   // Add this at the top of your existing agent-registry.json:
   "vars": {
     "workspace_root": "~/.openclaw",
     "master_agent": "amaster",
     "master_memory": "${vars.workspace_root}/workspace-${vars.master_agent}/memory"
   },
   // Update workspace paths to use placeholders:
   "agents": {
     "acode": {
       "workspace": "${vars.workspace_root}/workspace-acode"  // \x3C-- use placeholder
     }
   }
   

2. Verify with dry-run: bash scripts/init_sync.sh --dry-run

3. Re-run init: bash scripts/init_sync.sh (safe — skips existing files)

Compatibility notes

• Existing CHANGELOG.md, sentinel files, and .sync_journal.jsonl are fully compatible
• Agent-side pending_sync_*.md / SYNC.md / BOOTSTRAP.md format unchanged
• force_sync.sh positional args unchanged; new flags are additive

Files