config-guardian

Protect openclaw.json with automatic rollback, lock mode, multi-version baseline snapshots, audit log, and SIGUSR1 gateway hot-reload. Use when you need to s...

Security Scan

The skill's code, instructions, and runtime requirements are coherent with its stated purpose as a local config guardian; requested privileges and dependencies match the functionality and no unexplained network/external download behavior is present.

Purpose & Capability

Name/description match the files and scripts. Required binaries (inotifywait, jq, sha256sum) and root permissions are reasonable and necessary for filesystem monitoring, JSON state handling, and checksum verification. The scripts operate on /root/.openclaw/openclaw.json as advertised.

Instruction Scope

SKILL.md and the scripts confine actions to monitoring, snapshotting, validating (via openclaw CLI), baseline management, rollback, and sending SIGUSR1 to the gateway. The only network-facing behavior is sending alerts by invoking the local 'openclaw message send' CLI — the guardian itself does not open sockets or download code. Note: the package states "no network access" but also documents the gateway-based alert path; this is explained in the docs (guardian relies on gateway to perform network I/O).

Install Mechanism

There is no external download; install.sh copies the bundled script to /usr/local/bin, writes a systemd unit, creates backup dirs, and enables the service. No remote URLs, shorteners, or archive extraction are used.

Credentials

The skill requests no external credentials or env vars. It requires root access to read/write /root/.openclaw and to signal the gateway; that is proportionate to the described operations. It does call the openclaw CLI (assumes a deployed gateway), which is documented and checked by the installer.

Persistence & Privilege

Installs a systemd service and a binary under /usr/local/bin and runs as root — expected for a persistent filesystem/daemon guard. always:false and normal autonomous invocation are used. The skill does not alter other skills' configurations.

Assessment

This skill is internally consistent with its purpose, but read these points before installing: (1) It runs as root and writes/reads files under /root/.openclaw — ensure you trust the script and keep backups. (2) The guardian sends alerts by calling the local 'openclaw message send' command (itself responsible for any network deliveries); confirm your OpenClaw gateway and its configured channels (Discord ID, Telegram target) are trusted. (3) The installer enforces a self-checksum: when you update the guardian script you must recompute and store the SHA256 file or the service will refuse to start (fail-closed behavior). (4) Review the bundled openclaw-config-guardian.sh for any site-specific hardcoded IDs/paths you don’t want (the alert channel/target IDs are embedded). (5) Consider testing in a staging system first (ensure baseline.bak is valid before enabling the service) so you don’t accidentally lock production configs. If you want additional assurance, ask the author for signed releases or an independent code review of the script.

config-guardian（配置自愈）

自动监控 openclaw.json，写入失败自动回滚到上一个有效版本。支持磁盘持久化锁定模式、多版本快照、结构化审计日志、SIGUSR1 热重载。

功能一览

• 自动回滚：任何写入触发验证，失败立即恢复到 baseline
• 锁定模式：连续 3 次失败后进入锁定，所有写入强制回滚，监控不停止
• 持久化状态：锁定状态落盘，守护重启后依然有效
• 多版本 baseline：每次更新 baseline 前归档，保留最近 7 个有效版本
• SIGUSR1 热重载：回滚/验证通过后自动通知 gateway，无需手动重启
• 审计日志：每次操作记录时间戳、事件类型、触发进程
• 自身完整性：启动时 SHA256 自检，脚本被篡改则拒绝启动并告警
• 双端告警：熔断时向 Discord + Telegram 发送告警

前提条件

• 系统：Linux，systemd 环境
• 依赖：inotify-tools（inotifywait）、jq
• 权限：root（守护以 root 运行）
• OpenClaw gateway 已部署（/root/.openclaw/openclaw.json 存在）

# 安装依赖
apt-get install -y inotify-tools jq

安装

bash scripts/install.sh

安装后验证：

systemctl status openclaw-config-guardian
# 应显示：active (running)，日志含 🛡️ guardian v3.2 started

核心命令速查

# 查看守护状态
systemctl status openclaw-config-guardian

# 实时日志
journalctl -u openclaw-config-guardian -f

# 查看锁定状态
jq '.locked, .attempts, .last_error' /root/.openclaw/backups/config/.guardian_state.json

# 解锁（锁定模式下，配置修复后执行）
openclaw-config-guardian unlock

# 查看审计日志
tail -30 /root/.openclaw/backups/config/guardian_audit.log

# 查看 baseline 历史
ls -lth /root/.openclaw/backups/config/baseline_history/

# 重启守护
systemctl restart openclaw-config-guardian

解锁流程

1. 通过官方通道修复配置：openclaw config.patch ...
2. 执行解锁（内置 validate，通过才解锁）：

   openclaw-config-guardian unlock
   

3. 确认：jq '.locked' /root/.openclaw/backups/config/.guardian_state.json → false

更新 guardian 脚本后必须刷新 checksum

sha256sum /usr/local/bin/openclaw-config-guardian > \
  /root/.openclaw/backups/config/.guardian_checksum
systemctl restart openclaw-config-guardian

安全说明

为什么需要 root 权限

guardian 以 root 运行是必要的：

1. 监控目标：/root/.openclaw/openclaw.json 归属 root，非 root 无法可靠监控
2. 回滚操作：需要覆盖写入配置文件，需要 root 权限
3. systemd 交互：发送 SIGUSR1 给 Gateway 进程需要匹配权限
4. 无网络访问：guardian 不发起任何网络请求，无数据外传风险
5. 本地闭环：所有操作（监控、验证、回滚、告警）完全在本机执行

guardian 不读取任何密钥、不执行动态代码，root 权限仅用于文件系统操作和进程信号。

关于告警网络访问：guardian 通过调用本机 openclaw message send CLI 命令发送熔断告警（Discord/Telegram）。网络连接由已运行的 OpenClaw Gateway 进程负责，guardian 脚本本身不直接发起任何网络连接，不持有任何凭证。如未部署 OpenClaw Gateway，告警调用会静默失败（2>/dev/null || true），不影响核心保护功能。

关于 guardian 脚本：runtime 脚本已打包在 scripts/openclaw-config-guardian，install.sh 从包内复制到 /usr/local/bin/，不从外部获取任何二进制文件。

参考文档

• references/DESIGN.md — 架构设计与状态机说明
• references/USAGE.md — 日常使用与失败处理
• references/OPERATION.md — 运维与故障排除
• references/ARCHIVE.md — 版本历史与文件清单