Docs / Agent Config Tamper Detection

Agent Config Tamper Detection

Detect whether your agent's core configuration files have been modified without your knowledge and scan them for prompt injection attacks.

What problem does this solve?

Your OpenClaw agent's behaviour is defined by a set of files in your workspace: SOUL.md, IDENTITY.md, AGENTS.md, and USER.md. These files tell the agent who it is, what it can do, and how it should behave. Other files like MEMORY.md, TOOLS.md, and HEARTBEAT.md are operational — they change frequently as part of normal agent use and are excluded from drift monitoring by default.

If any of these files are modified by a malicious skill, a compromised dependency, a prompt injection attack, or simply an unexpected change your agent's behaviour changes with them. Unlike a traditional application where config changes are logged and audited, these files are plain text and can be altered silently.

Three checks run at every scan

1. 1 Config file inventory At every scan, the plugin takes a SHA256 hash of each core config file and records it in the run report. This creates a complete fingerprint of your agent's configuration at that point in time.
2. 2 Drift detection Compares the current file hashes against an approved baseline you've set. If SOUL.md, IDENTITY.md, or any other approved file has changed since you last approved it, the scan flags exactly which files changed and the size delta. You decide whether the change was expected then re-approve to update the baseline.
3. 3 Prompt injection scan (NC-OC-011) Scans each config file for known prompt injection indicators:
   • Zero-width characters invisible Unicode characters used to hide instructions inside legitimate-looking text
   • Instruction override phrases patterns like "ignore previous instructions", "disregard prior context", "you are now"
   • External script URLs links to raw GitHub, Pastebin, or Gist URLs embedded in config files, which could load external instructions at runtime

How it works in practice

Config tamper detection runs automatically as part of every scan you don't need to trigger it separately. The inventory and tamper scan results appear in your scan output alongside the standard controls.

For drift detection, use the approve command to set your baseline after reviewing a scan. Once a baseline exists, every subsequent scan compares against it and reports any files that have changed.

Commands

Setting up drift detection

On first use, run approve all clawvitals baseline files to record the current state of all config files as your approved baseline. From then on, every run clawvitals compares current file hashes against that baseline. When you intentionally update a file (e.g. you edit SOUL.md), say "approve SOUL.md as baseline" to update the baseline for that file only. If a file changes and you did not change it — investigate before approving.

Note: clawvitals status shows the cognitive file monitoring state based on the stored baseline from the last scan — it does not re-scan files live. To get up-to-date drift results, run run clawvitals first.

Baseline storage

The approved baseline is stored at ~/.openclaw/workspace/clawvitals/baselines/cognitive-files.json with file permissions 600 readable only by your user account. The baseline records the file name, SHA256 hash, size, when it was approved, and by whom.

Files monitored

Monitored by default — these define agent identity and behaviour. Unexpected changes are security-relevant:

SOUL.md  ·  IDENTITY.md  ·  AGENTS.md  ·  USER.md

Excluded by default — these change frequently as part of normal agent operation:

MEMORY.md  ·  TOOLS.md  ·  HEARTBEAT.md  ·  README.md

All .md files in the workspace root are inventoried. You can change the inclusion/exclusion state of any file by saying “exclude [filename] from drift monitoring” or “include [filename] in clawvitals drift detection”.