Skip to main content
@visiq/openclaw-plugin is an OpenClaw plugin that routes every tool call through VisIQ’s action and retrieval governance and feeds the audit trail. It installs from npm and requires OpenClaw 2026.5.18 or newer.

​
What it does

The plugin registers six OpenClaw hooks: The retrieval facet is pre-seeded for ten tool names: web_search, x_search, web_fetch, tool_search, tool_describe, get_account, get_transactions, get_devices, check_watchlist, and search_knowledge. Namespaced tools (mcp__brave__web_search) match on the segment after the last __. The set is a fast-path default, not a governance boundary — tools outside it still get full action governance on every call. Decisions evaluate in-process against the agent’s rule bundle, which the plugin pre-warms before the first call — registering a human approval is the only decision-path network call. New agents auto-provision in monitor mode on first contact: every decision is evaluated and recorded, but nothing is blocked until you switch the agent to enforce (see Verifying the install).

​
Interactive setup

You need a harness API key (vq_test_ or vq_prod_). The guided setup on the OpenClaw card under Integration → Connectors mints a scoped key for you; you can also create one under Settings → Harness Keys. Then install and configure the plugin:
The --dangerously-force-unsafe-install flag is required. OpenClaw’s install scanner blocks any plugin that reads environment variables and makes network calls, flagging it as “possible credential harvesting”. The VisIQ plugin does exactly that by design — it reads VISIQ_API_KEY and sends governance decisions to your VisIQ backend — so this is an expected false positive for a governance plugin. Without the flag the install is hard-blocked.
openclaw gateway run runs the gateway in the foreground and serves the Control UI at http://localhost:18789. To run it as a background service (launchd / systemd / schtasks) instead:

​
Automated / CI setup

For pipelines, containers, and anywhere without an interactive TTY, supply credentials via environment variables and run the gateway headless:
Optional:
For image builds and provisioning scripts, the package also ships a visiq-openclaw-plugin helper bin (npx @visiq/openclaw-plugin configure) that writes credentials into ~/.openclaw/openclaw.json — interactive on a TTY, or non-interactive from the VISIQ_* env vars when there is none.

​
Credential resolution precedence

The plugin resolves credentials in this order (highest priority first):
  1. CLI flags: --api-key / --agent-id / --base-url
  2. Environment variables: VISIQ_API_KEY / VISIQ_AGENT_ID / VISIQ_BASE_URL (VISIQ_ENDPOINT is accepted as a base-URL fallback; VISIQ_BASE_URL wins when both are set)
  3. JSON file at the path in VISIQ_CONFIG_PATH
  4. ~/.openclaw/openclaw.json → plugins.entries["@visiq/openclaw-plugin"].config
  5. Interactive prompt (only when both stdout and stdin are terminals)

​
Fail-open vs fail-closed

  • Unconfigured (missing credentials): every hook no-ops. A single structured warning is emitted to stderr explaining how to configure the plugin. This fail-open behavior is by design — the plugin should never break OpenClaw on first install before credentials are provisioned.
  • Governance evaluation errors: fail-closed. The tool call is blocked with a clear [VisIQ ...]-prefixed reason.
  • Telemetry errors: never affect agent behavior. Failures are logged to stderr and swallowed — telemetry is best-effort.

​
Verifying the install

Start the gateway and trigger a web_search. In the dashboard at app.visiqlabs.com, the agent appears under Harness → Agents tagged as a CLI Harness, and the decision appears in the Harness → Runtime Enforcement ledger. Governed decisions feed the audit trail, including signed decision receipts. When the recorded decisions look right, open the agent on the Agents page and switch its mode from Monitor — Log only to Enforce — Block. The mode is server-authoritative and per-agent; the plugin picks it up with its next rule bundle refresh.