Skill: stevensongxx/agent-config-sync (version 1.5.1)

--- name: agent-config-sync description: |- Synchronize configuration versions across OpenClaw multi-agent deployments. Tracks changes in a master workspace using sentinel version files and CHANGELOG, then dispatches to downstream agents via sessions_send or file-based pending_sync fallback. Each agent independently checks for updates on startup (BOOTSTRAP.md) and heartbeat (HEARTBEAT.md). Designed for users running 2+ specialized agents who need consistent system/agent/OpenClaw configurations. Triggers on: sync, configure, version management, multi-agent coordination. --- # Agent Config Sync (v1.5) Keep configuration consistent across multiple OpenClaw agents using version tracking, CHANGELOG-based change detection, and automatic sync dispatch with journal-backed two-phase commit. > **⚡ Quick Start (30 seconds to running):** > ```bash > # Step 1: Install > clawhub install agent-config-sync > > # Step 2: Run setup wizard (interactive, no manual editing needed) > cd ~/.openclaw/skills/agent-config-sync > bash scripts/wizard.sh > > # Step 3: Done! 🎉 > # - Agent registry auto-detected > # - Sync infrastructure created > # - HEARTBEAT integration added > # - All agents ready to receive syncs > ``` > > **Non-interactive?** Use `bash scripts/wizard.sh --auto` to auto-detect everything. > > **Prefer manual?** See [Installation](#installation) below for step-by-step instructions. > > **New in v1.5**: Interactive setup wizard (`scripts/wizard.sh`), `--auto` mode for init_sync.sh (zero-config auto-detection), enhanced SYNC.md with quick start guide and cheat sheet, simplified onboarding. > > **New in v1.4**: Full version conflict management — dispatch lock, loop detection, self-upgrade isolation, batch mode, rollback snapshots, TTL-based expiry, offline catch-up, and agent-side version collapse. See [Version Conflict Management](#version-conflict-management-v14) for details. > > **Security**: This skill writes to agent workspaces across your OpenClaw deployment. Read the full [SECURITY.md](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 **Option A (Recommended): Run the setup wizard** ```bash cd ~/.openclaw/skills/agent-config-sync bash scripts/wizard.sh ``` The wizard auto-detects your agents and generates `agent-registry.json` — no manual editing. **Option B: Manual configuration** Edit `references/agent-registry.json` — this is the only file you need to change for your deployment: | Variable | Location | Example | Description | |----------|----------|---------|-------------| | `workspace_root` | `vars` in registry | `~/.openclaw` | Base path for all agent workspaces | | `master_agent` | `vars` in registry | `amaster` | ID of your coordination/master agent | | `master_memory` | `vars` in registry | `${workspace_root}/workspace-amaster/memory` | Path to master's memory directory | | (each agent) | `agents` in registry | See below | Add/remove/rename agents to match your setup | **Example** — after customization for user "Alice" with agents `alice-dev`, `alice-biz`, `alice-ops`: ```json { "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 | Type | Examples | |:----:|----------| | 🖥️ System code | Quant system, price compare, data pipelines | | 🤖 Agent config | SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md | | ⚙️ OpenClaw config | Models, skills, service addresses, plugins | | 🎯 Task config | API keys, cron jobs, data sources, ports | --- ## Installation ### Prerequisites - OpenClaw with 2+ agents - One designated "master" coordination agent - `clawhub` CLI installed ### Option A: Interactive Wizard (Recommended for New Users) ```bash clawhub install agent-config-sync cd ~/.openclaw/skills/agent-config-sync bash scripts/wizard.sh ``` The wizard walks you through: 1. Environment detection (auto-finds your agents) 2. Registry configuration (auto-generates from your workspace) 3. Infrastructure initialization (one click) 4. HEARTBEAT integration (auto-appended) 5. Completion report (status summary + next steps) ### Option B: One-Command Auto Setup ```bash clawhub install agent-config-sync bash ~/.openclaw/skills/agent-config-sync/scripts/init_sync.sh --auto ``` Auto-detects all agent workspaces, generates registry, and initializes everything — zero prompts. ### Option C: Manual Step-by-Step #### Step 1: Install the Skill ```bash 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](#️-customization-variables) table above, or the English quickstart at `references/quickstart.md`. #### Step 3: Initialize Sync Infrastructure ```bash 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 ```bash # Check version files cat ~/.openclaw/workspace-<master>/memory/.current_system_version # should be v1.0 # Check agent sync files ls ~/.openclaw/workspace-*/SYNC.md ``` --- ## Version Conflict Management (v1.4) ### Conflict Types | Type | Scenario | Frequency | Impact | |:-----|:---------|:---------:|:------:| | **Concurrent Change** | Two agents submit version changes simultaneously | High | Medium | | **Cross-Session Stale** | Agent restarts and finds outdated `pending_sync` files | Medium | Low | | **Offline Catch-Up** | Agent misses one or more sync cycles | Medium | High | | **Self-Reference (Self-Upgrade)** | agent-config-sync's own files need updating | Low | High | | **Multi-Agent Coordination** | Change requires specific ordering across agents | Medium | Medium | | **Rollback** | Need to revert a problematic version change | Low | High | ### Conflict Detection Mechanisms | Mechanism | Location | What It Detects | |:----------|:---------|:----------------| | Version Sentinel Comparison | Master HEARTBEAT item 12 | `.current_system_version` ≠ `.last_sync_version` | | Dispatch Lock | Master HEARTBEAT item 12 | Concurrent dispatch prevention (< 2min window) | | Loop Detection | Master HEARTBEAT item 12 | 3+ consecutive same-version journal records | | TTL Expiry Check | Agent BOOTSTRAP/HEARTBEAT | `now > 过期时间` → delete stale pending_sync | | Version Folding | Agent side | Multiple `pending_sync_*.md` files → fold by version | | `.agent_sync_version` Gap | Agent side | Local version < current system version → offline gap | | Self-Protect Blacklist | Master dispatch | CHANGELOG impact range includes sync's own files | | Snapshot Verification | Agent rollback | SHA256 checksums on restored files | ### Agent-Side Pending Sync Priority Matrix When an agent discovers multiple `pending_sync_*.md` files, it processes them in this order: ``` Priority Type Handle ───────── ──────────────── ────────────────────────────── 1 (first) Expired files Delete immediately (now > 过期时间) 2 Superseded files Delete (lower version number, depends_on chain covered) 3 Isolated syncs Must process before normal syncs (self-upgrade isolation) 4 Revert syncs Revert to target version from snapshot 5 (last) Normal syncs Apply in version order, respecting depends_on chain ``` **Version Collapse Rule**: If multiple `pending_sync_v3.1`, `pending_sync_v3.2`, `pending_sync_v3.3` exist AND v3.3's `**前置**` chain covers all intermediate versions → apply only v3.3 and delete v3.1/v3.2. ### Version Folding Algorithm ``` Agent discovers pending_sync_*.md files: 1. 删除已过期的文件（生成时间 > TTL，默认 24h） 2. 删除已被 supersede 的文件（版本号更低，且被更新版本的 depends_on 链覆盖） 3. 对剩余文件按版本号排序 → 从最早的开始执行 4. 如果文件头包含 "前置" 依赖 → 先检查前置是否已处理 - 若前置未处理 → 按依赖链逐步升级 - 若前置已处理 → 可直接应用 5. 应用变更前创建前置快照（memory/.sync_snapshots/<VERSION>_pre/） 6. 应用变更后更新 .agent_sync_version 7. 删除已处理的 pending_sync 文件 ``` --- ## Agent-Side Version Collapse (v1.4) ### Overview When an agent discovers multiple `pending_sync_*.md` files (e.g., after being offline or during a period of rapid changes), it uses version collapse to avoid processing every intermediate version. The goal is to safely "jump" from the agent's current version to the latest applicable version in a single step. ### Decision Flow ``` Agent discovers N pending_sync_*.md files (N ≥ 1): 1. PARSE all file headers: - Extract: 版本, 前置, 生成时间, 过期时间, 类型 2. CLEANUP expired: FOR EACH file: IF now > 过期时间: DELETE file LOG "Stale sync expired: <filename>" 3. DETECT superseded: SORT remaining files by 版本 DESC FOR EACH file from latest to earliest: Walk depends_on chain from latest version IF current version is in chain → all older files are superseded DELETE all files whose version < latest_version AND covered by chain 4. CLASSIFY remaining files: GROUP by 类型: - isolated_sync → process BEFORE normal syncs - revert_sync → restore from snapshot - pending_sync → normal version upgrade 5. ORDER execution: isolated_sync files (ascending version) ↓ revert_sync files (ascending target version) ↓ normal pending_sync files (ascending version, respecting depends_on chain) 6. EXECUTE each file: a. CHECK depends_on: IF 前置 > .agent_sync_version → ERROR (chain broken, request Master) b. CREATE snapshot: mkdir .sync_snapshots/<VERSION>_pre/ + backup affected files c. APPLY changes from CHANGELOG d. UPDATE .agent_sync_version = 版本 e. DELETE processed file 7. VERIFY: Check .agent_sync_version matches latest processed version Confirm no remaining pending_sync files (or that remaining files have valid depends_on > current) ``` ### Version Comparison ``` Version format: v<MAJOR>.<MINOR>[.<PATCH>] is_newer("v3.2", "v3.1") → true (MINOR increment) is_newer("v3.2.1", "v3.2") → true (PATCH increment) is_newer("v3.1", "v3.2") → false is_newer("v4.0", "v3.9") → true (MAJOR increment) is_same("v3.1", "v3.1") → true ``` ### Edge Cases | Case | Behavior | |------|----------| | Single pending file | Direct application (no collapse needed) | | Chain broken (v3.1, v3.3 but no v3.2 dependency) | Process v3.1 first, then v3.3 | | Chain complete (v3.1 depends v3.0; v3.3 depends v3.1) | Jump directly to v3.3 | | Mixed types (pending + revert) | Revert takes priority; if revert target > current, normal syncs after | | Corrupt file (unparseable header) | Skip, log error, request Master re-dispatch | | Same version, 2 files (duplicate) | Keep newest by 生成时间, delete older | --- ## Self-Upgrade Isolation (v1.4) ### Problem agent-config-sync's own files (SKILL.md, scripts/, SECURITY.md, etc.) may need updating. But if the sync system dispatches changes to itself through normal channels, it can trigger self-referential sync loops. ### Solution: Isolated Sync Flow When a CHANGELOG entry's impact range includes paths in the `self_protect.blacklist`: 1. **Detection**: Master HEARTBEAT item 12 checks if the change affects agent-config-sync itself 2. **Isolation**: Generates `isolated_sync_<VERSION>_<SHA>.md` in Master's `memory/` directory 3. **Notification**: Appends a notice to each agent's `BOOTSTRAP.md` (not dispatched via normal flow) 4. **Agent Action**: On next startup, agent detects the BOOTSTRAP notice and requests the isolated sync 5. **No sentinel file**: Does not use `pending_sync` file mechanism — avoids normal dispatch loop ### Configuration Configured in `agent-registry.json`: ```json "self_protect": { "enabled": true, "skip_agents": ["agent-config-sync"], "isolated_sync": true, "blacklist": ["HEARTBEAT.md", "BOOTSTRAP.md", "SKILL.md", "scripts/", "SECURITY.md", "references/"], "sync_own_version_file": "skills/agent-config-sync/.sync_own_version", "allow_bootstrap_only": true } ``` ### Self-Protect Blacklist Paths listed in `blacklist` are quarantined from normal dispatch. Any CHANGELOG entry affecting these paths triggers the isolated sync flow instead. --- ## Batch Mode (v1.4) ### Overview When multiple rapid changes occur within a time window, batch mode merges them into a single cumulative dispatch instead of triggering one sync per version. ### Configuration ```json "batch": { "mode": "auto", "window_sec": 300 } ``` ### Behavior 1. HEARTBEAT detects version mismatch 2. Instead of immediate dispatch, opens a batch window (default: 5 min) 3. All version bumps within the window are accumulated 4. When window closes → merge all changes into one `pending_sync` file 5. Uses highest version number among batched changes 6. Combines all CHANGELOG sections ### Merge Rules - Sort all batched versions → use the highest version - Concatenate CHANGELOG entries in version order - Generate single SHA256 signature over combined content - Single dispatch covers all intermediate changes --- ## Rollback Mechanism (v1.4) ### Overview When a version change causes problems, the system supports controlled rollback to a previous version using pre-sync snapshots. ### Rollback Flow ``` 1. TRIGGER (Master): - Set .current_system_version to the rollback target version - HEARTBEAT detects: current < last_sync → recognizes as rollback - Creates revert_sync_<FROM>_to_<TO>_<SHA>.md in each agent workspace 2. APPLY (Agent): - Detects revert_sync file on HEARTBEAT/BOOTSTRAP check - Restores files from memory/.sync_snapshots/<TARGET>_pre/ - Verifies SHA256 checksums from snapshot_manifest.json - Updates .agent_sync_version to target version - Deletes revert_sync file 3. VERIFY (All): - .current_system_version == .last_sync_version (stable state) - No pending_sync or revert_sync files remain ``` ### Snapshot Directory Structure ``` memory/.sync_snapshots/ ├── v3.2_pre/ │ ├── TOOLS.md.bak │ ├── SOUL.md.bak │ ├── AGENTS.md.bak │ └── snapshot_manifest.json └── v3.3_pre/ ├── config.json.bak └── snapshot_manifest.json ``` ### snapshot_manifest.json Format ```json { "sync_version": "v3.2", "snapshot_time": "2026-05-16T08:30:00Z", "previous_version": "v3.1", "files": { "TOOLS.md": "sha256:a1b2c3...", "SOUL.md": "sha256:d4e5f6..." } } ``` ### Rollback Safety - **Pre-condition**: Agent must have a snapshot directory matching the target rollback version - **SHA256 verification**: All restored files verified against snapshot manifests - **No partial rollback**: Atomic restore (all files succeed or none) - **Loop prevention**: Rollback records are `type=revert` — not re-triggered by normal dispatch - **Manual confirmation**: Requires explicit version bump to trigger --- ## Configuration ### Agent Registry (`references/agent-registry.json`) The single source of truth. Fields: | Field | Description | |-------|-------------| | `vars.workspace_root` | Root directory for all agent workspaces | | `vars.master_agent` | ID of the coordination agent (sends syncs) | | `vars.master_memory` | Path to master's memory directory (uses placeholders) | | `agents.<id>.name` | Display name (English) | | `agents.<id>.name_zh` | Display name (Chinese) — optional | | `agents.<id>.role` | Short role description | | `agents.<id>.workspace` | Path to agent workspace (uses `${vars.workspace_root}`) | | `sync.*` | Sync behavior config (sentinel filenames, prefix, limits) | ### CHANGELOG Format All version entries must follow the structured format defined in `references/sync-setup.md`: ```markdown ## vX.Y (YYYY-MM-DD) **Change Type**: <category> **Affected Agents**: <which agents> **Author**: <who made the change> **Priority**: normal | high | critical ### Added / Changed / Deprecated - <description> ``` ### Language Scripts support `--lang en` and `--lang zh` (default). Use `--lang en` for English output: ```bash 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: ```markdown ## 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: ```bash 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_<sha>.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 ```bash cd ~/.openclaw/skills/agent-config-sync # Preview the version change bash scripts/force_sync.sh --dry-run ~/.openclaw/workspace-<master>/memory v3.0 v3.1 # Execute (--confirm required for write operations) bash scripts/force_sync.sh --confirm ~/.openclaw/workspace-<master>/memory v3.0 v3.1 ``` After running, the next heartbeat detects `current (v3.1) != last_sync (v3.0)` and dispatches. ### Checking Sync Status ```bash # Check version sentinel files cat ~/.openclaw/workspace-<master>/memory/.current_system_version cat ~/.openclaw/workspace-<master>/memory/.last_sync_version # Check journal for recent sync records tail -5 ~/.openclaw/workspace-<master>/memory/.sync_journal.jsonl # Check for pending syncs on an agent ls ~/.openclaw/workspace-<agent>/pending_sync_*.md ``` ### Demo Mode (Learning) ```bash 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 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 | Symptom | Likely Cause | Fix | |---------|-------------|-----| | No dispatch on heartbeat | HEARTBEAT item 12 not added to master | Follow `references/sync-setup.md` exactly; verify grep `agent-config-sync` in master's HEARTBEAT.md | | Dispatched but not processed | Agent missing BOOTSTRAP sync check | Re-run `init_sync.sh` for that agent's workspace | | `pending_sync` files piling up | Agent never deletes after processing | Check agent's HEARTBEAT.md has sync check with delete step | | Same version synced repeatedly | `.last_sync_version` not updated | Run `force_sync.sh` to reset, or check journal for stale records | | Version sentinel files (`.current_system_version`, `.last_sync_version`) are read-only | Accidental `chmod 444` or permission inheritance | **All writes silently fail** — version appears unchanged. Fix: `chmod 664 memory/.current_system_version memory/.last_sync_version` | | Dispatched but log says "permission denied" | Sentinel files or journal files have wrong ownership | `ls -la memory/.current_system_version memory/.last_sync_version memory/.sync_journal.jsonl` → verify writable by the user running OpenClaw | ### Version Conflicts | Symptom | Likely Cause | Fix | |---------|-------------|-----| | Wrong version on agent | Partial sync interrupted | Check journal for `status=prepared` records; master re-dispatches on next heartbeat | | Multiple `pending_sync` files | Back-to-back changes | Process latest version first; all files are cumulative | | SHA256 verification fails | File tampered or truncated | Request master to re-dispatch that version | | "Backup failed" in force_sync | Memory dir permission issue | `chmod 755 memory/` and retry | ### Journal Issues | Symptom | Likely Cause | Fix | |---------|-------------|-----| | Stale prepared records (>24h) | Agent was offline too long | Mark as abandoned in journal, re-trigger sync with `force_sync.sh` | | Journal growing too large | Many sync records | Archive old `committed` entries periodically | | Corrupt journal line | Partial write or disk issue | Delete the last line (corrupt), re-trigger sync | ### 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 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 < 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: | Resource | Chinese | English | |----------|:---:|:---:| | `SKILL.md` (this file) | — | ✅ Full English | | `references/quickstart.md` | — | ✅ English quickstart for new users | | `references/sync-setup.md` | ✅ Full Chinese | — (code pseudocode is language-agnostic) | | `references/sync-journal.md` | ✅ Full Chinese | — (JSONL format is language-agnostic) | | `scripts/init_sync.sh` | `--lang zh` (default) | `--lang en` | | `scripts/force_sync.sh` | `--lang zh` (default) | `--lang en` | | Registry agent names | `name_zh` field | `name` field | | Generated SYNC.md | Chinese template | English template (via `--lang en`) | | Generated CHANGELOG.md | Chinese template | English template (via `--lang en`) | **Using English**: ```bash # 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`**: ```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" // <-- 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 | File | Purpose | |------|---------| | `SKILL.md` | This skill definition | | `SECURITY.md` | Security model, permissions, and user consent flow | | `references/quickstart.md` | 🆕 English quickstart for new users | | `references/sync-setup.md` | HEARTBEAT item 12 + structured CHANGELOG spec | | `references/pending-sync-template.md` | pending_sync file template (version-named) | | `references/sync-journal.md` | Journal-based two-phase commit mechanism | | `references/agent-registry.json` | Single source of truth for agent IDs and workspaces | | `scripts/init_sync.sh` | Full setup in one command (now reads registry; supports --auto) | | `scripts/force_sync.sh` | Trigger immediate sync detection | | `scripts/revert_sync.sh` | Trigger version rollback | | `scripts/wizard.sh` | 🆕 Interactive setup wizard for new users |

path: README.md
content: # agent-config-sync v1.5

**Keep configuration consistent across multiple OpenClaw agents** — zero-touch setup, interactive wizard, version tracking, and automatic sync dispatch.

[![Version](https://img.shields.io/badge/version-1.5.0-blue)](_meta.json)
[![OpenClaw](https://img.shields.io/badge/OpenClaw-enabled-green)](https://openclaw.ai)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Bash](https://img.shields.io/badge/pure-bash-orange)](scripts/)

---

## 🎯 What It Does

When you run 2+ OpenClaw agents, keeping their configurations in sync is painful. `agent-config-sync` automates this:

```
Master Agent detects change
        │
        ▼
  Reads CHANGELOG.md
        │
        ▼
  Generates sync manifest
        │
        ├─→ Agent 1: pending_sync_v3.1_a1b2c3.md
        ├─→ Agent 2: pending_sync_v3.1_a1b2c3.md
        └─→ Agent 3: pending_sync_v3.1_a1b2c3.md
                │
                ▼
       Agents apply → verify → cleanup
```

**Syncs**: System code · Agent configs (SOUL/IDENTITY/TOOLS) · OpenClaw config · Task configs · API keys

---

## ⚡ Quick Start (30 seconds)

```bash
# 1. Install
clawhub install agent-config-sync

# 2. Run wizard (interactive, auto-detects everything)
cd ~/.openclaw/skills/agent-config-sync
bash scripts/wizard.sh

# 3. Done! 🎉
#    All agents now have sync infrastructure.
#    Changes are auto-dispatched on next Master heartbeat.
```

**Prefer non-interactive?**
```bash
bash scripts/wizard.sh --auto     # Zero prompts
bash scripts/init_sync.sh --auto  # Even faster
```

---

## ✨ Features

| Feature | Description |
|:--------|:------------|
| 🧙 **Interactive Wizard** | 5-step guided setup with auto-detection — no manual file editing |
| 🤖 **--auto Mode** | One-command setup that detects workspaces, generates registry, and initializes everything |
| 📊 **Version Tracking** | Sentinel files (`.current_system_version`, `.last_sync_version`) for monotonic versioning |
| 🔄 **Auto Dispatch** | Master HEARTBEAT detects version mismatch → dispatches to all agents via `sessions_send` or file fallback |
| 📝 **CHANGELOG-driven** | Structured `CHANGELOG.md` — read only latest section, not entire history |
| 🗄️ **Two-Phase Commit** | `.sync_journal.jsonl` ensures atomicity — PREPARE → DISPATCH → COMMIT |
| 🔍 **Offline Catch-Up** | Agents that miss sync cycles get cumulative catch-up packages |
| 🛡️ **Rollback** | Pre-sync snapshots + SHA256 verification for safe rollbacks |
| 🔒 **Dispatch Lock** | Prevents concurrent sync dispatch (< 2min window) |
| 🔁 **Loop Detection** | 3+ consecutive same-version → block and alert |
| 📦 **Batch Mode** | Merges rapid consecutive changes into single dispatch |
| 🏝️ **Self-Upgrade Isolation** | agent-config-sync's own files use isolated upgrade flow |
| 🌐 **Bilingual** | Full Chinese + English output (`--lang en|zh`) |
| 🎭 **Demo Mode** | `--demo` creates a full temp deployment for learning |
| 🔐 **Path Validation** | Only writes to `~/.openclaw/workspace-*` — no external access |

---

## 📋 Requirements

- **OpenClaw** running with 2+ agents
- One designated "master" coordination agent
- `clawhub` CLI installed
- Bash 4.0+ (no Python/Perl required)

---

## 🏗️ Architecture

```
skills/agent-config-sync/
├── SKILL.md                    # Full documentation
├── SECURITY.md                 # Security model & permissions
├── README.md                   # This file
├── _meta.json                  # Package metadata
├── scripts/
│   ├── wizard.sh               # 🆕 Interactive setup wizard (v1.5)
│   ├── init_sync.sh            # Infrastructure initialization
│   ├── force_sync.sh           # Trigger immediate sync detection
│   └── revert_sync.sh          # Version rollback trigger
├── references/
│   ├── agent-registry.json     # Single source of truth (agent IDs, paths)
│   ├── sync-setup.md           # HEARTBEAT item 12 + CHANGELOG spec
│   ├── sync-journal.md         # Two-phase commit mechanism
│   ├── pending-sync-template.md # Sync file template
│   └── quickstart.md           # Quickstart for new users
└── reports/
    └── ...                     # Evaluation reports & repair logs
```

---

## 🚀 Usage

### Daily Operations

```bash
# Record a change (master agent)
echo "v1.1" > ~/.openclaw/workspace-amaster/memory/.current_system_version

# Or use the force_sync helper
bash scripts/force_sync.sh --confirm ~/.openclaw/workspace-amaster/memory v1.0 v1.1
```

### Check Status

```bash
# Master version
cat ~/.openclaw/workspace-amaster/memory/.current_system_version
cat ~/.openclaw/workspace-amaster/memory/.last_sync_version

# Pending syncs on an agent
ls ~/.openclaw/workspace-acode/pending_sync_*.md
```

### Rollback

```bash
bash scripts/revert_sync.sh --dry-run ~/.openclaw/workspace-amaster/memory v1.0
bash scripts/revert_sync.sh --confirm ~/.openclaw/workspace-amaster/memory v1.0
```

### Demo / Learning

```bash
bash scripts/init_sync.sh --demo --lang en
```

---

## ⚙️ Configuration

The wizard auto-generates `references/agent-registry.json`. To customize manually:

```json
{
  "vars": {
    "workspace_root": "~/.openclaw",
    "master_agent": "amaster"
  },
  "agents": {
    "acode": { "name": "Coding Agent", "role": "Development", "workspace": "..." },
    "ainvest": { "name": "Investment Agent", "role": "Finance", "workspace": "..." }
  }
}
```

---

## 🔒 Security

All scripts enforce:
- `--confirm` required for writes (use `--dry-run` first)
- Path whitelist: only `~/.openclaw/workspace-*` allowed
- Cross-agent isolation: each agent accesses only its own workspace
- Atomic writes: `tempfile → sync → mv` (no partial sentinel files)
- No network, no API calls, no credential access

Full details: [SECURITY.md](SECURITY.md)

---

## 🌐 Internationalization

```bash
# English output
bash scripts/wizard.sh --lang en
bash scripts/init_sync.sh --lang en

# Chinese output (default)
bash scripts/wizard.sh --lang zh
```

---

## 📄 License

MIT

---

## 🙋 FAQ

**Q: How is this different from just copying files?**
A: It's event-driven (version mismatch → dispatch), journaled (two-phase commit), and handles edge cases (offline agents, conflicts, rollbacks).

**Q: Do I need to run this on every agent?**
A: No. Only the Master agent dispatches. Other agents receive `pending_sync_*.md` files and check for them on startup/heartbeat (automatically set up by `init_sync.sh`).

**Q: What if an agent is offline?**
A: The Master writes a `pending_sync_<VERSION>.md` file to the agent's workspace. On next startup, the agent detects and applies it. If multiple versions piled up, version collapse jumps to the latest.

**Q: Can I use this without `clawhub`?**
A: Yes — just clone or copy the skill directory to `~/.openclaw/skills/agent-config-sync/` and run `scripts/wizard.sh`.


path: SECURITY.md
content: # Security Model & Permissions

## Permission Scope

`agent-config-sync` requires the following permissions:

### Required
| Permission | Reason | Scope |
|-----------|--------|-------|
| **File read** (master memory) | Read version files & CHANGELOG for sync dispatch | Master agent's `memory/` directory only |
| **File write** (agent workspaces) | Write `pending_sync_*.md` when agents are offline | Agent workspace root only |
| **File read** (agent workspaces) | Check for pending sync files on startup | Agent own workspace only |
| **File append** (agent configs) | Add sync check to BOOTSTRAP.md / HEARTBEAT.md | Agent own workspace only |

### Not Required
- ❌ Network access (no external API calls)
- ❌ Execute arbitrary commands
- ❌ Access outside `~/.openclaw/workspace-*`
- ❌ Read secrets or credentials
- ❌ Modify other installed skills

## Permission Boundaries

### Path Validation
All scripts validate that target paths start with `$workspace_root/workspace-$agent_id/`.
Paths outside this pattern are rejected with an error.

```
✅ ~/.openclaw/workspace-acode/BOOTSTRAP.md    → allowed
❌ /etc/passwd                                   → rejected
❌ ~/.openclaw/openclaw.json                     → rejected (not in a workspace)
```

### File Permission Requirements

**Critical: Sentinel files must be writable**

The version sentinel files (`.current_system_version`, `.last_sync_version`, `.sync_journal.jsonl`) **must be writable** (`rw-rw-r--` / 664).

If set to read-only (e.g., `r--r--r--` / 444), **all version writes silently fail**:
- No version changes are persisted — `.current_system_version` stays at the old value
- HEARTBEAT item 12 detects no difference and skips dispatch
- The sync system appears broken even though infrastructure is healthy
- No error is logged by the atomic write wrapper

**Fix**: `chmod 664 memory/.current_system_version memory/.last_sync_version memory/.sync_journal.jsonl`

**Verification** (run after init/force_sync):
```bash
ls -la memory/.current_system_version memory/.last_sync_version memory/.sync_journal.jsonl
# Should show -rw-rw-r-- not -r--r--r--
```

### User Consent Flow
```
Step 1: --dry-run (always available)
  → Preview every file that will be created/modified
  → No changes are made

Step 2: --confirm (required for write operations)
  → After --dry-run, user must re-run with --confirm
  → Short summary printed before execution

Step 3: Execution
  → Changes logged to stdout + sync journal
  → Backup created for modified existing files
```

## Cross-Agent Isolation
Each agent can only read/write its OWN workspace files.
AMaster (the coordination agent) can write pending_sync files to all agent workspaces,
but only as part of the two-phase commit journal flow.

## Update & Rollback
- All changes are journaled to `.sync_journal.jsonl`
- Backups created before modifying existing files
- Version sentinel files allow deterministic recovery

## Version Conflict Scenarios

### Master Agent Permissions During Conflict

During version conflicts (concurrent changes, offline agents, rollbacks), the Master agent:

| Action | Permission | Boundary |
|--------|:----------:|----------|
| Read `.sync_journal.jsonl` for loop detection | ✅ Allowed | Master `memory/` only |
| Read `pending_sync_*.md` from agent workspaces | ✅ Allowed | Only `~/.openclaw/workspace-*/` |
| Write `pending_sync_*.md` to agent workspaces | ✅ Allowed | Only `~/.openclaw/workspace-*/` |
| Write `revert_sync_*.md` to agent workspaces | ✅ Allowed | Only `~/.openclaw/workspace-*/` |
| Write `isolated_sync_*.md` for self-upgrade | ✅ Allowed | Master `memory/` only; dispatch via isolated flow |
| Create snapshot backups in agent workspaces | ✅ Allowed | Only `~/.openclaw/workspace-*/memory/.sync_snapshots/` |
| Read `.agent_sync_version` from agent workspaces | ✅ Allowed | Only `~/.openclaw/workspace-*/memory/` |
| Delete expired `pending_sync_*.md` files | ✅ Allowed | Only expired (> TTL) files in agent workspaces |

### Agent Permissions During Conflict

| Action | Permission | Boundary |
|--------|:----------:|----------|
| Read own `pending_sync_*.md` files | ✅ Allowed | Own workspace only |
| Read own `.agent_sync_version` | ✅ Allowed | Own `memory/` only |
| Create snapshots before applying sync | ✅ Allowed | Own `memory/.sync_snapshots/` only |
| Delete processed `pending_sync_*.md` files | ✅ Allowed | Own workspace only |
| Restore from snapshots during rollback | ✅ Allowed | Own `memory/.sync_snapshots/` only |
| Query Master for latest version | ✅ Allowed | Via `sessions_send` (existing channel) |

### Snapshot Directory Whitelist

The only allowed snapshot paths:

```
✅ ~/.openclaw/workspace-<agent>/memory/.sync_snapshots/<version>_pre/
✅ ~/.openclaw/workspace-<agent>/memory/.sync_snapshots/<version>_pre/snapshot_manifest.json
✅ ~/.openclaw/workspace-<agent>/memory/.sync_snapshots/<version>_pre/*.bak
❌ ~/.openclaw/workspace-<agent>/memory/.sync_snapshots/../../../etc/passwd
❌ /tmp/snapshots/
```

### Conflict-Related Security Guarantees

1. **No network access** — All conflict resolution is file-system-local (within `~/.openclaw/`)
2. **No credential access** — Conflict detection reads only sentinel files and journal metadata
3. **Atomic writes** — All sentinel file updates use `_atomic_write()` (tempfile + sync + mv)
4. **TTL gating** — Expired `pending_sync` files are deleted, never applied
5. **Loop detection** — Journal scanning prevents infinite sync loops (hard limit: 3 consecutive same-version records)
6. **Isolated self-upgrade** — agent-config-sync's own files are quarantined, never dispatched via normal flow
7. **Snapshot immutability** — Snapshots are read-only after creation; rollback reads from snapshot, never modifies it

## Rollback Security

### Snapshot Creation (Pre-Sync)

Before applying any sync change, the agent creates a snapshot:

1. **Directory**: `memory/.sync_snapshots/<VERSION>_pre/`
2. **Scope**: Only files listed in the CHANGELOG impact range (not a full workspace backup)
3. **Integrity**: Each file's SHA256 checksum recorded in `snapshot_manifest.json`
4. **Permissions**: Snapshots inherit the agent's own file permissions (no privilege escalation)

### Rollback Execution

1. **Trigger**: Master sets `.current_system_version` to a version < `.last_sync_version`
2. **Dispatch**: Generates `revert_sync_<from>_<to>_<sha>.md` — type=revert in journal
3. **Agent-side**: Restores files from snapshot directory, verifies SHA256 checksums
4. **Atomic restore**: All files restored or none (abort on first mismatch)
5. **Cleanup**: Revert file deleted after successful restore; journal marked reverted

### Rollback Attack Surface Mitigation

| Threat | Mitigation |
|--------|------------|
| Malicious revert targeting wrong version | SHA256 verification against snapshot manifest |
| Partial restore leaving mixed state | Atomic restore (all-or-nothing) |
| Infinite revert loops | Journal `type=revert` prevents re-dispatch; manual confirmation required |
| Snapshot tampering | SHA256 pre-computed at snapshot creation; verified at restore time |
| Unauthorized snapshot access | Snapshots inherit agent workspace permissions; no new paths created |




path: _meta.json
content: ownerId: kn7at24f2mbp2nzbvyprwbaws186t9g8
slug: agent-config-sync
version: 1.5.1
publishedAt: 1778918730000

path: references/agent-registry.json
content: {
  "version": "1.4.0",
  "comment": "Customize this file for your deployment — vars section + keyed agents object. v1.4 adds self_protect, batch, and sync configuration.",
  "vars": {
    "workspace_root": "~/.openclaw",
    "master_agent": "amaster",
    "master_memory": "${vars.workspace_root}/workspace-${vars.master_agent}/memory"
  },
  "agents": {
    "acode": {
      "name": "大师",
      "name_en": "Coding Agent",
      "role": "编程开发",
      "workspace": "${vars.workspace_root}/workspace-acode"
    },
    "ainvest": {
      "name": "元宝",
      "name_en": "Investment Agent",
      "role": "投资分析",
      "workspace": "${vars.workspace_root}/workspace-ainvest"
    },
    "alive": {
      "name": "牛奶",
      "name_en": "Assistant Agent",
      "role": "生活助理/写作",
      "workspace": "${vars.workspace_root}/workspace-alive"
    }
  },
  "sync": {
    "sentinel_dir": "memory",
    "journal_file": ".sync_journal.jsonl",
    "changelog_file": "CHANGELOG.md",
    "pending_prefix": "pending_sync",
    "max_changelog_sections": 10,
    "ttl_hours": 24,
    "dispatch_timeout_sec": 120
  },
  "self_protect": {
    "enabled": true,
    "skip_agents": ["agent-config-sync"],
    "isolated_sync": true,
    "blacklist": [
      "HEARTBEAT.md",
      "BOOTSTRAP.md",
      "SKILL.md",
      "scripts/",
      "SECURITY.md",
      "references/",
      "agent-registry.json"
    ],
    "sync_own_version_file": "skills/agent-config-sync/.sync_own_version",
    "allow_bootstrap_only": true
  },
  "batch": {
    "mode": "auto",
    "window_sec": 300
  }
}


path: references/agent-setup.md
content: # Per-Agent Auto-Sync Setup

For each agent workspace, create or append to these files:

## 1. SYNC.md (new file)

```markdown
# 配置同步机制 — 自动获取变更通知

## 检查入口
每次启动/激活时，先检查工作空间下的 `pending_sync.md` 是否存在且非空。

## 同步检查流程
```
启动/激活 → 检查工作目录存在 pending_sync.md?
  ├─ ✅ 有内容 → 读取变更摘要 → 更新本地 MEMORY.md
  │              → 根据变更内容更新本地配置
  │              → 删除 pending_sync.md（标记已处理）
  │              → 回复 AMaster 确认已同步
  └─ ❌ 无文件或空 → 无需同步
```

## 同步源
- 完整变更日志: `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md`
- 当前版本: `/home/admin/.openclaw/workspace-amaster/memory/.current_system_version`
- 主动查询: 可向 AMaster 询问最新版本状态

## 重要
- 使用量化交易系统 / 比价系统前，必须确认版本信息
- 如果有 pending_sync.md 但未处理，不要使用相关系统功能
```

## 2. BOOTSTRAP.md (append to end)

```markdown
## 启动检查 — 配置同步
- [ ] 检查工作目录下是否存在 `pending_sync.md`
  - 存在 → 读取变更摘要，更新 MEMORY.md，删除 pending_sync.md
  - 不存在 → 无需同步
- [ ] 使用量化系统/比价系统前先确认版本
```

## 3. HEARTBEAT.md (append to end)

```markdown
## ⭐ 配置同步检查（每次 heartbeat 执行）
- [ ] 检查工作目录下是否存在 `pending_sync.md`
  - 存在且非空 → 读取变更摘要，更新 MEMORY.md，删除文件
  - 不存在 → 跳过
```


path: references/pending-sync-template.md
content: # pending_sync Template

**v1.4**: Enhanced file header with TTL/expiry, depends_on chain, and agent version tracking fields. Backward compatible — new fields are additive.

## Template Content

```markdown
# pending_sync_<VERSION>_<SHA>.md

**类型**: pending_sync
**版本**: <VERSION>
**前置**: <PREVIOUS_VERSION>
**生成时间**: <GENERATED_AT>
**过期时间**: <EXPIRES_AT>  (24h 后)
**紧急程度**: <PRIORITY>
**签名**: <SHA256>

## 变更清单
- [ ] 🖥️ 系统代码变更
- [ ] 🤖 智能体配置变更
- [ ] ⚙️ OpenClaw 系统配置变更
- [ ] 🎯 任务/工作配置变更

## 详情
请读取 `/home/admin/.openclaw/workspace-amaster/memory/CHANGELOG.md` 中 `<VERSION>` 对应的章节。

## 操作指令
1. 创建前置快照: mkdir -p memory/.sync_snapshots/<VERSION>_pre/
2. 备份受影响文件到快照目录
3. 应用变更
4. 更新 memory/.agent_sync_version = <VERSION>
5. 删除本文件
```

## Template Fields

| Field | Required | Format | Example |
|-------|:--------:|--------|---------|
| `**类型**` | ✅ | `pending_sync` / `revert_sync` / `isolated_sync` | pending_sync |
| `**版本**` | ✅ | `vX.Y` | v3.5 |
| `**前置**` | ⬜ | `vX.Y` or `none` | v3.4 |
| `**生成时间**` | ✅ | ISO 8601 with timezone | 2026-05-16T08:30:00+08:00 |
| `**过期时间**` | ✅ | ISO 8601 (24h after generated) | 2026-05-17T08:30:00+08:00 |
| `**紧急程度**` | ✅ | `normal` / `high` / `critical` | high |
| `**签名**` | ✅ | SHA256 first 12 hex chars | a1b2c3d4e5f6 |

## SHA256 Signature

The `<SHA256>` value in the filename and template body is computed as:

```
sha256("pending_sync_<VERSION>_" + 变更摘要)
```

Take the first 12 hex characters as the short signature.

### Purpose
- Receiving agent can verify file integrity
- Prevents tampered or truncated sync notifications
- Short 12-char format keeps filenames manageable

### Verification (in agent-side logic)

```python
import hashlib

def verify_sync_file(filename, expected_version, change_summary):
    expected_sig = hashlib.sha256(
        f"pending_sync_{expected_version}_{change_summary}".encode()
    ).hexdigest()[:12]
    actual_sig = filename.split("_")[-1].replace(".md", "")
    return expected_sig == actual_sig
```

## File Naming Convention

| Pattern | Example |
|---------|---------|
| Version sync | `pending_sync_v3.1_a1b2c3d4e5f6.md` |
| Startup discovery | `ls pending_sync_*.md` to list all pending |
| Revert sync | `revert_sync_v3.3_to_v3.2_a1b2c3d4.md` |
| Isolated sync | `isolated_sync_v1.4_a1b2c3d4.md` |

## Cleanup

Each agent independently deletes its own pending file after processing:

```bash
# Agent-side cleanup after sync applied
rm -f pending_sync_*.md revert_sync_*.md isolated_sync_*.md
```

The file persists as long as the agent hasn't applied the sync. If the same version file is generated twice (e.g., dispatch retry), the content is idempotent — the agent can re-apply safely.

## TTL & Expiry

By default, pending_sync files expire **24 hours** after generation. The agent's BOOTSTRAP/HEARTBEAT checks should:

1. Parse `**过期时间**` from the file header
2. If `now > 过期时间` → delete the expired file, request latest version from Master
3. If `now <= 过期时间` → proceed with sync processing

TTL is configurable via `agent-registry.json` → `sync.ttl_hours` (default: 24).


path: references/quickstart.md
content: # Quickstart — agent-config-sync for New Users

**5-minute setup** to keep configuration consistent across all your OpenClaw agents.

---

## Before You Start

You need:
- OpenClaw running with 2+ agents
- A "master" agent that coordinates others
- `clawhub` CLI installed

### Example Setup (Alice)

Alice has 3 agents:

| Agent ID | Purpose | Workspace |
|----------|---------|-----------|
| `alice-dev` | Software development | `~/.openclaw/workspace-alice-dev` |
| `alice-biz` | Business analysis | `~/.openclaw/workspace-alice-biz` |
| `alice-ops` | Operations & scheduling | `~/.openclaw/workspace-alice-ops` |

Alice uses `alice-ops` as her master/coordination agent.

We'll use Alice's setup as a concrete example throughout this guide.

---

## Step 1: Install the Skill

```bash
clawhub install agent-config-sync
```

This installs to `~/.openclaw/skills/agent-config-sync/`.

---

## Step 2: Customize the Agent Registry

Edit `~/.openclaw/skills/agent-config-sync/references/agent-registry.json` to match your agents:

```json
{
  "version": "1.2",
  "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": "Software Development",
      "workspace": "${vars.workspace_root}/workspace-alice-dev"
    },
    "alice-biz": {
      "name": "Alice Biz",
      "role": "Business Analysis",
      "workspace": "${vars.workspace_root}/workspace-alice-biz"
    },
    "alice-ops": {
      "name": "Alice Ops",
      "role": "Coordination",
      "workspace": "${vars.workspace_root}/workspace-alice-ops"
    }
  }
}
```

> **Key**: Change `master_agent` in `vars` and replace all agent entries under `agents`. Scripts read from this file — this is the **only place** you need to configure agent names.

---

## Step 3: Initialize Sync Infrastructure

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

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

# Run the actual setup
bash scripts/init_sync.sh
```

This creates:
- Version sentinel files in your master agent's `memory/` directory
- `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

Add this to your master agent's `HEARTBEAT.md`:

```markdown
12. ⭐ **Config Change Sync** — Check for unsynchronized system/config changes
    - **Sentinel**: `memory/.last_sync_version`
    - Compare against `memory/.current_system_version` on every heartbeat
    - If version mismatch detected → dispatch to all downstream agents:
      a. Read latest section from `memory/CHANGELOG.md`
      b. `sessions_send` to each agent (or write `pending_sync_<VERSION>_<SHA>.md` as fallback)
      c. Record results in `.sync_journal.jsonl`
    - On success → update `memory/.last_sync_version` = `memory/.current_system_version`
    - Sync failure does NOT block heartbeat — logged to journal only
```

See `references/sync-setup.md` for the full specification.

---

## Step 5: Verify

```bash
# Check version files were created
cat ~/.openclaw/workspace-alice-ops/memory/.current_system_version
# Expected: v1.0

cat ~/.openclaw/workspace-alice-ops/memory/.last_sync_version
# Expected: v1.0

# Check agent sync files exist
ls ~/.openclaw/workspace-alice-dev/SYNC.md ~/.openclaw/workspace-alice-biz/SYNC.md
# Both should exist
```

---

## Step 6: Test a Sync

```bash
# Bump version to trigger sync on next heartbeat
echo "v1.1" > ~/.openclaw/workspace-alice-ops/memory/.current_system_version

# Or use the force_sync helper:
bash ~/.openclaw/skills/agent-config-sync/scripts/force_sync.sh \
  ~/.openclaw/workspace-alice-ops/memory v1.0 v1.1
```

The next heartbeat on your master agent will detect the version mismatch and dispatch config changes to all agents.

---

## Customizing Further

### Change master memory path

If your master agent stores memory elsewhere, update `vars.master_memory` in `.agent_registry`:

```json
"vars": {
  "master_memory": "/custom/path/to/memory"
}
```

### Use as non-master agent

The skill's sync reception is agent-side: each agent checks for `pending_sync_*.md` files on startup (BOOTSTRAP) and every heartbeat (HEARTBEAT). The `init_sync.sh` script sets this up automatically.

### Language

Scripts support Chinese and English output:

```bash
bash scripts/init_sync.sh --lang en    # English output
bash scripts/init_sync.sh --lang zh    # Chinese output (default)
```

---

## Troubleshooting

| Problem | Check |
|---------|-------|
| "Registry not found" in init_sync | Run from skill directory: `cd ~/.openclaw/skills/agent-config-sync` |
| Agents not receiving syncs | Verify master agent has HEARTBEAT item 12 |
| `pending_sync` files pile up | Agent may not have BOOTSTRAP sync check — re-run `init_sync.sh` |
| Path errors | Check `vars.workspace_root` in `agent-registry.json` — expand `~` to full path if needed |

---

## Next Steps

- Read `SKILL.md` for architecture overview and daily operations
- Read `references/sync-setup.md` for HEARTBEAT implementation details
- Read `references/sync-journal.md` for the two-phase commit mechanism


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)