Deterministic Governance

Deterministic governance and memory compaction layer for OpenClaw. Ensures reproducible agent behavior.

Deterministic Governance transforms OpenClaw from a flexible AI assistant into a predictable, auditable execution system suitable for long-running agent deployments and CI environments. This is not a productivity plugin — it's a governance framework that enforces execution discipline with explicit safety guarantees. The author's philosophy is clear: 'If you want experimentation, use OpenClaw alone. If you want discipline, use OpenClaw Deterministic.' The plugin operates across three governance layers: execution classification (tiered A/B/C for safe, governed modification, and destructive operations), memory pressure management (token-estimated semantic memory with configurable hard limits and risk thresholds), and canonical integrity verification (SHA256 hashes for deterministic templates with tamper detection). Each execution tier defines whether a diff preview, confirmation, or auto-execution is allowed — preventing silent behavioral drift. The system assumes drift is inevitable and makes it visible rather than trying to prevent it entirely. It detects manual edits outside the deterministic flow, provides structured backup snapshots before any template mutation, and supports reverts to previous snapshots. The upgrade command verifies canonical integrity before applying changes, refuses to overwrite drifted files (unless --force), and supports --dry-run for safe evaluation. With only 60 weekly downloads, this is a niche tool for serious deployments — production OpenClaw setups, CI-integrated governance pipelines, and environments requiring full auditability. The CLI tool (oc-deterministic) provides machine-readable JSON output, deterministic backup snapshots, governance event logging, and CI integration via exit codes. Not for casual users who just want a helpful AI assistant.

Tags: utility, governance

Use Cases

  • Production OpenClaw deployments requiring predictable, auditable behavior
  • CI/CD pipelines with automated governance checks via exit codes
  • Long-running agent systems where behavioral drift must be detected and reported
  • Environments requiring tamper detection and canonical integrity verification
  • Memory-constrained deployments needing hard token limits on semantic memory

Tips

  • Run oc-deterministic doctor --json for machine-readable health checks in CI pipelines
  • Use oc-deterministic status for concise health summaries in automated environments
  • Set RISK_THRESHOLD_PERCENT to 85% to get early warnings before hitting the hard memory limit
  • Use --dry-run on upgrade to preview changes before applying them
  • Pair with CI exit codes for automated governance checks in deployment pipelines
  • Keep violation_logging enabled to track governance events over time
  • Use oc-deterministic revert --list to see available snapshots before reverting

Known Issues & Gotchas

  • This installs as a global npm package, not as an OpenClaw plugin via openclaw plugins install
  • The --force flag on upgrade bypasses integrity checks — use with caution
  • Snapshot backups accumulate in ~/.openclaw/backups/deterministic/ — clean up periodically
  • The doctor command must pass before the system considers itself healthy
  • Drift detection flags ANY manual edit — even intentional ones — as a deviation
  • Memory hard limits are token-estimated, not exact — actual token counts may vary
  • Revert restores only deterministic-managed files, not arbitrary workspace changes

Alternatives

  • Workspace Governance
  • Squad
  • Custom AGENTS.md rules

Community Feedback

This is not an assistant plugin. It is a governance layer. Determinism over autonomy. No silent behavior changes. Explicit classification before execution. Auditable state at all times.

— GitHub

The deterministic state management is an aggregated mess. Generally, the abstraction between deterministics and non-deterministics is a mess.

— Reddit r/vibecoding

Yeah it seems like 90% of the skills it can use could be replaced with vibe coded python that would be deterministic, safer and faster.

— Reddit r/LocalLLaMA

Frequently Asked Questions

Is this an OpenClaw plugin or a separate tool?

It's a separate global CLI tool installed via npm install -g. It wraps and constrains your OpenClaw workspace rather than running inside OpenClaw as a plugin. The install command (oc-deterministic install) applies governance templates to your workspace.

What are the execution tiers?

Tier A is safe (auto-execute allowed), Tier B is governed modification (diff preview and confirmation required), and Tier C is destructive/structural (strictest controls). Each tier prevents silent behavioral drift.

What happens when drift is detected?

The doctor command flags drifted files — any manually edited outside deterministic flow. The upgrade command refuses to overwrite drifted files unless you use --force. Drift is made visible rather than silently corrected.

Can I use this with Workspace Governance?

They address overlapping but different concerns. Deterministic Governance focuses on execution classification and memory compaction. Workspace Governance focuses on write discipline and audit reports. Using both may create conflicting governance rules — test carefully.

How does the memory compaction work?

Semantic memory is token-estimated and compared against a configurable HARD_LIMIT (default 1200 tokens). When usage exceeds the RISK_THRESHOLD_PERCENT (default 85%), warnings are logged. At the hard limit, expansion is blocked.

Can I revert changes made by the deterministic system?

Yes. Before any template mutation, snapshots are stored at ~/.openclaw/backups/deterministic/. Use oc-deterministic revert --list to see snapshots and oc-deterministic revert --to <id> to restore.

Configuration Examples

Install and Verify

npm install -g @sdotwinter/openclaw-deterministic
oc-deterministic install
oc-deterministic doctor

Custom Memory Limits

# ~/.openclaw/.deterministic.json
{
  "semantic": {
    "HARD_LIMIT": 800,
    "RISK_THRESHOLD_PERCENT": 75
  },
  "governance": {
    "violation_logging": true
  }
}

CI Pipeline Integration

# In CI script:
oc-deterministic doctor --json
if [ $? -ne 0 ]; then
  echo 'Governance check failed'
  exit 1
fi
oc-deterministic status

Installation

openclaw plugins install @sdotwinter/openclaw-deterministic