VITNA for OpenClaw

VITNA for OpenClaw puts a containment check in front of the agent's tool calls. Every call OpenClaw routes through the plugin (shell, files, browser, messaging, MCP) is checked by VITNA first; calls to tools you mark as risky wait for a person, and if nobody answers, the call does not run. No API key can decide a hold, including the agent's own. On a claimed account, each decision is an Ed25519-signed record you can verify offline.

Scope: it covers the tool calls OpenClaw routes through the plugin. Detection is heuristic, not a sandbox.

Status: documented, not yet tested end to end (see Compatibility). The hook is tested against a stand-in host that follows OpenClaw's documented hook rules; no run with a hold held, approved and denied on a real OpenClaw gateway is recorded yet. Free tier; MIT.

Install: openclaw plugins install clawhub:@costrinity/vitna-openclaw once it is listed on ClawHub, or openclaw plugins install npm:@costrinity/vitna-openclaw. Setup: https://vitna.costrinity.xyz/connect, OpenClaw (VITNA plugin) tab. OpenClaw version: 2026.10.1 or later. The plugin is checked against OpenClaw 2026.10.1's plugin SDK; older versions are untested.

What it does

• Allow: the call runs, with exactly the arguments VITNA checked.
• Block: the call is not run, and the agent is told VITNA's reason.
• Hold: the hook waits for a person's decision in VITNA (Approve or Deny on your dashboard). Approved runs the call; denied or expired blocks it. If the hold is still open when the hook stops waiting (holdWaitSeconds, default 110), the call is blocked with a note that the same call will run once if the agent retries it within 10 minutes of an approval.
• Anything that goes wrong blocks the call: VITNA unreachable, an error, no key, the hook timing out (OpenClaw blocks a call when a hook times out). It never fails open.
• Decisions come only from VITNA. OpenClaw's own approval prompt is not used, so nothing in the agent's session can approve a hold.
• The arguments VITNA checked are the ones that run, when it runs last. OpenClaw runs the last arguments a hook handler returns. The plugin registers at a very low priority (Number.MIN_SAFE_INTEGER; higher runs first) and returns the arguments it checked, so another plugin's earlier rewrite is replaced by them. See Limits for when it does not run last.

Set up

1. Install the plugin in your OpenClaw gateway (the exact install command for an npm plugin is in OpenClaw's plugin docs; from ClawHub: openclaw plugins install clawhub:@costrinity/vitna-openclaw once it is listed there).
2. Configure it under plugins.entries.vitna in ~/.openclaw/openclaw.json, and let the hook wait as long as a hold:

{
  "plugins": {
    "entries": {
      "vitna": {
        "enabled": true,
        "config": {
          "ownerId": "<your VITNA owner id>",
          "apiKey": "<your VITNA API key>",
          "policy": { "allowed_actions": ["*"], "hold_actions": ["exec", "write", "edit", "apply_patch"] },
          "holdWaitSeconds": 110
        },
        "hooks": { "timeouts": { "before_tool_call": 120000 } }
      }
    }
  }
}

Hook timeouts can go up to 600000 ms (10 minutes); keep holdWaitSeconds about 10 seconds below it. ownerId and apiKey can come from VITNA_OWNER_ID and VITNA_API_KEY instead.

The aquarium look tool

The plugin registers vitna_choose_look: the agent picks one emoji and one of 12 colours for how it appears in its owner's VITNA aquarium. It is cosmetic only, never held, and the agent cannot set its name. Your agent sees it once you add vitna_choose_look to tools.allow in your OpenClaw config. The hook answers the call itself, so OpenClaw shows it as a blocked call whose reason is the reply; no other tool with that name ever runs.

Limits

• Other plugins can get around the argument rule. A plugin registered after VITNA at the same priority, or at a lower one such as -Infinity, runs after it and can change the arguments. A higher-priority plugin that asks for OpenClaw's own approval with rewritten arguments freezes them: VITNA's are ignored, and the rewritten ones run once that approval is granted. Keep VITNA as the only plugin that rewrites or approves tool calls.
• Keep the hold wait below the hook timeout. If OpenClaw's hook timeout is shorter than holdWaitSeconds, OpenClaw blocks the call when it expires, and an approval made after that is spent without running the call.
• Without a policy, every tool is allowed and nothing is held by name; VITNA's detectors can still hold a call they flag (a destructive shell command, a secret on its way out).
• It sees only what goes through OpenClaw's tool hook. Reports say MCP tools on the claude-cli backend skip the hook or arrive renamed mcp__server__tool (openclaw issue #155946): test that before you rely on it there, and list anything outside it in unwrapped for the session record.
• Holding on exec holds every shell command; the policy matches tool names, not what the command does. VITNA's detectors still read the command text.
• Detection is heuristic pattern matching, not a sandbox.
• Signed records are for claimed VITNA accounts; a trial key gets none.

MIT licence. COSTRINITY INC., Regina, Saskatchewan. https://vitna.costrinity.xyz