@clawdreyhepburn/openclaw-ovid

July 22, 2026 · View on GitHub

Give every AI sub-agent its own ID badge — automatically.

This is a plugin for OpenClaw (an AI agent runtime). You install it once, and from then on every time your AI assistant spawns a helper ("sub-agent") to go do some task, this plugin quietly stamps that helper with a tamper-proof identity document. No code changes to your agent. It just happens.

If that sentence raised questions, the rest of this README explains it from scratch. You do not need any security or identity background to follow along.

Why would I want this?
The core idea in one picture
What this plugin actually does
Install
Your first mandate (the important part)
Worked example
Configuration
Command-line tools
What this plugin does NOT do
How it fits with its sibling plugins
FAQ

Why would I want this?

Modern AI assistants don't do everything themselves. When you give one a big job, it often spawns smaller helper agents to split up the work — one to read your files, one to search the web, one to run a command. This is like a manager delegating to a team.

Here's the problem: by default, every helper inherits the full power of the thing that created it.

Imagine you hire a contractor to paint one room, and instead of a key to that room, you hand them the keys to your entire house, your car, and your bank account — "just in case." That's how AI sub-agents work out of the box. A helper spawned only to summarize a document technically also has the power to delete files, send emails, or run any command — because it inherited all of it.

Most of the time nothing goes wrong. But "most of the time" is not a security model. If a helper gets confused, or reads a malicious instruction hidden in a web page, or simply misbehaves, it can do far more damage than its actual job ever required.

This plugin fixes that by giving each helper a specific, limited, verifiable set of permissions — and nothing more.

The core idea in one picture

        YOU (the human — the ultimate source of authority)
         │
         │  you run an AI assistant
         ▼
   ┌──────────────────┐
   │  Main assistant  │   has broad power (that's fine — you supervise it)
   └────────┬─────────┘
            │  spawns a helper to "summarize report.pdf"
            │
            │  ← this plugin steps in HERE, automatically
            │     and stamps the helper with an ID badge that says:
            │        "may READ files. may not do anything else."
            ▼
   ┌──────────────────┐
   │  Helper agent    │   can ONLY read. If it tries to delete a file
   │  (sub-agent)     │   or send an email, that's off-badge.
   └──────────────────┘

The "ID badge" is a small, cryptographically signed digital document. It records:

Who this helper is,
Who created it (traceable all the way back to you),
What it is allowed to do (its "mandate"),
When it expires (badges are temporary).

Because the badge is signed with unforgeable digital math (the same kind of cryptography that secures websites), nobody can counterfeit one or tamper with it.

What this plugin actually does

Concretely, once installed, this plugin hooks into one moment: the instant your assistant spawns a sub-agent. At that moment it:

Mints an identity document (we call it an OVID — think of it as the ID badge) for the new helper.
Attaches the helper's list of allowed actions (its mandate — the rules printed on the badge) to that document.
Signs it so it can't be forged, and links it to the badge of whoever spawned it, forming a traceable chain back to you.
Hands the badge to the helper as part of its starting instructions.

It also gives you three manual tools (ovid_mint, ovid_verify, ovid_inspect) if you ever want to create or examine a badge by hand.

Important: on its own, this plugin issues badges but does not check them at every action. Issuing the badge and enforcing the badge are deliberately two separate jobs (like a company that has one department print ID cards and a separate security desk that checks them at the door). The checking is done by its sibling plugin, @clawdreyhepburn/openclaw-ovid-me. You'll usually install both. See How it fits.

Install

# Full recommended stack (badge printer + security desk + deployment ceiling)
openclaw plugins install @clawdreyhepburn/openclaw-ovid
openclaw plugins install @clawdreyhepburn/openclaw-ovid-me
openclaw plugins install @clawdreyhepburn/carapace
openclaw carapace setup

Or just this plugin if you only want badges issued (no enforcement yet):

openclaw plugins install @clawdreyhepburn/openclaw-ovid

OpenClaw picks plugins up automatically after install. The very first time OVID runs, it generates a cryptographic keypair (the private "signing pen" that stamps badges) under ~/.ovid/keys/. This happens once and is reused. Keep that folder private — it's the root of trust for every badge you issue.

What you get at each layer:

Package	Job	Default safety
`openclaw-ovid`	Issue signed badges on every `sessions_spawn`	Always on once installed
`openclaw-ovid-me`	Check badges on every tool call	Starts in `dry-run` (log only; flip to `enforce` when logs look clean)
`carapace`	Human-set ceiling for tools/shell/APIs	`defaultPolicy: allow-all` fallback + your forbid files; forbids always win

Your first mandate (the important part)

A mandate is just the list of things a helper is allowed to do. If you don't specify one, the plugin gives the helper a safe, narrow default: read, search, and summarize only.

To grant a helper more (or different) permissions, you write the rules directly into the task you hand it, wrapped in a special marker:

[OVID_MANDATE]
permit(principal, action in [Ovid::Action::"read", Ovid::Action::"write"], resource);
[/OVID_MANDATE]

That block says: "this helper may read and write, and nothing else." The plugin reads the block, bakes those rules into the helper's badge, and removes the block from the task text before the helper sees it (so the helper just gets a clean task).

The rules are written in Cedar, a small, plain-looking permission language created by Amazon. You don't need to learn much. The pattern is almost always:

permit(principal, action in [Ovid::Action::"<verb>", ...], resource);

Common verbs: read, search, write, exec (run commands), summarize. So:

You want the helper to…	Put this in the `[OVID_MANDATE]` block
Only read, search, and summarize (the default)	(omit the block — you get this for free)
Read and write files	`permit(principal, action in [Ovid::Action::"read", Ovid::Action::"write"], resource);`
Read and run commands	`permit(principal, action in [Ovid::Action::"read", Ovid::Action::"exec"], resource);`
Do anything (use sparingly!)	`permit(principal, action, resource);`

Why put it in the task text instead of a settings field? Because the "spawn a helper" tool doesn't have a permissions field to fill in — the task description is the one channel that reliably reaches the plugin. It also keeps the permission grant right next to the job description, where it's easy to review. This is a deliberate design choice: permissions are attached per task, not assigned as fixed "roles." Every delegation is its own explicit, minimal grant.

You can optionally also set a custom expiry with [OVID_TTL:3600] (seconds) somewhere in the task; otherwise the default lifetime applies.

Worked example

Suppose your main assistant is asked to "clean up the logs folder." It decides to spawn a helper. In the helper's task, your assistant (or you, in its instructions) includes:

[OVID_MANDATE]
permit(principal, action in [Ovid::Action::"read", Ovid::Action::"exec"], resource);
[/OVID_MANDATE]
Delete every *.log file in ./logs older than 30 days.

What happens behind the scenes:

1. Assistant calls "spawn helper" with the task above.
2. This plugin intercepts the spawn:
      • reads the [OVID_MANDATE] block → "read + exec allowed"
      • mints a signed badge with exactly those two permissions
      • strips the block out
      • gives the helper the clean task: "Delete every *.log file…"
        plus its badge.
3. Helper starts work. Its badge now travels with it.
4. When the helper tries to RUN a delete command, the companion
   enforcement plugin checks the badge: "exec allowed? yes." → proceeds.
5. If that helper tried to, say, SEND AN EMAIL, the badge says
   nothing about email → the enforcement plugin flags/blocks it.

You get delegation that narrows power at each step instead of copying it wholesale.

Configuration

You normally don't need to configure anything. If you want to, these are the settings (shown with their defaults):

Setting	Default	What it means
`keyDir`	`~/.ovid/keys/`	Where the signing keypair is stored.
`defaultTtl`	`1800` (30 min)	How long a badge lasts if no `[OVID_TTL]` is given.
`maxTtl`	`86400` (24 h)	Hard ceiling on badge lifetime.
`maxChainDepth`	`5`	How many levels of "helper spawns a helper spawns a helper…" are allowed. (In today's OpenClaw, spawned helpers usually can't spawn their own helpers, so most installs never go past the first level — this is a safety ceiling for future nested delegation.)
`defaultMandate`	read/search/summarize	The permissions a helper gets when no `[OVID_MANDATE]` block is provided.
`autoMint`	`true`	Whether to automatically badge every spawned helper. Turn off to only mint badges manually.

Command-line tools

openclaw ovid status   # Show whether your signing keypair exists and its fingerprint
openclaw ovid keygen   # Generate (or regenerate) the signing keypair

And three tools your assistant can call directly:

ovid_mint — create a badge for a given set of permissions.
ovid_verify — check that a badge is genuine, unexpired, and traceable to you.
ovid_inspect — decode and pretty-print a badge's contents (without verifying it), handy for debugging.

What this plugin does NOT do

It does not block anything by itself. It issues badges. Checking a badge on every action and denying off-badge actions is the job of the companion plugin, openclaw-ovid-me. Install both for real protection.
It does not decide your organization's overall rules. A separate project, Carapace, lets you the human set an absolute ceiling ("no agent, ever, may run rm") that no badge can override.
It is not a login system for humans. It's about the identities of automated AI helpers, not people.

How it fits with its sibling plugins

Think of a secure building:

   Carapace                openclaw-ovid            openclaw-ovid-me
   (this is the       →    (this plugin —      →    (the security desk —
    building's rules:       the badge printer:       checks every badge
    what's allowed at       stamps each helper        at every door and
    all, set by YOU)        with its permissions)     stops off-badge moves)

Carapace — the building's master rulebook. The absolute limits you set as the human.
openclaw-ovid (you are here) — the badge printer. Issues each helper a signed, limited ID.
openclaw-ovid-me — the security desk. Reads each badge and actually allows or denies each action.

The two OVID plugins are usually installed together. This one gives helpers their identity and permissions; the other enforces them.

For the underlying identity technology (the badge format, the signing and chain-of-trust math), see the library this plugin is built on: @clawdreyhepburn/ovid.

FAQ

Do I have to write Cedar policies to use this? No. Out of the box, helpers get safe read, search, and summarize permissions automatically. You only write a mandate when you want to grant more than that.

What happens if I install this but not the enforcement plugin? Badges get issued but nothing checks them, so behavior is unchanged — you just have a nice audit trail of who was spawned with what permissions. Install openclaw-ovid-me to make the badges actually restrict behavior.

Is my signing key ever sent anywhere? No. It's generated and stays on your machine in ~/.ovid/keys/. Badges are signed locally. Nothing phones home.

A badge expired mid-task — is that bad? Badges are deliberately short-lived (default 30 minutes) so a leaked or forgotten one can't be abused forever. For longer jobs, set a longer [OVID_TTL:...] or raise defaultTtl.

"OVID" stands for what? OpenClaw Verifiable Identity Document. It's just our name for the signed ID badge.