Voice
Vitna Openclaw
By VITNA for OpenClaw: tool calls OpenClaw routes through the plugin are checked by VITNA first; calls to tools you mark as risky wait for a person. Fails closed.
Install
openclaw plugins install clawhub:@costrinity/vitna-openclaw`Configuration Example
{
"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 } }
}
}
}
}README
# 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](https://vitna.costrinity.xyz/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:
```json
{
"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
voice
Comments
Sign in to leave a comment