QVeris Plugin for OpenClaw

OpenClaw plugin that gives agents dynamic capability discovery and tool calling via the QVeris API.

What it does

Three tools are registered into the agent's context once the plugin is loaded:

Choose QVeris when task fit, data quality/freshness, provider comparison, fallback, or the user's request favors it; it is not a mandatory gateway when another connected tool is a better fit. Within QVeris, the default path is qveris_discover → qveris_call. Use qveris_inspect only when selection or valid request construction needs contract details that discovery omitted or may have made stale.

For provider comparison, Inspect every candidate when current scope or a complete contract must be confirmed; a Discover summary is not confirmation. If a budget decision requires a current Probe cost quote, do not Call until the host obtains it; this three-tool plugin does not expose Probe. This restriction does not apply to fresh business data such as a stock quote; obtain that with Call. Reuse only exact routes; rebuild current parameters and Call again for current/latest/today/time-sensitive data.

Session reuse contract

• Discover responses are cached in memory for the same normalized exact query and limit (90 seconds by default). refresh: true bypasses and replaces that entry.
• A successful Call records a capability hint (tool_id, discovery query/provenance, parameter contract, metadata source/expiry, usage count, and timestamps). It never stores Call parameter values, credentials, business results, or sensitive user values.
• Hints appear only on a later exact normalized capability query and expire after 30 minutes by default. Different coverage or freshness requirements should be expressed in the capability query and therefore do not match.
• clear_capability_memory: true on Discover removes hints for that exact normalized query. rememberSuccessfulCapabilities: false or a zero memory TTL disables them.
• The short-lived Discover response cache, discovery provenance, parameter contract, and successful-capability hint expire independently. A cached response keeps its original acquisition time. Inspect can refresh the contract of a still-valid route, but cannot revive expired discovery provenance; run Discover again after route expiry.
• An omitted parameter contract requires Inspect before the first Call; an explicit empty contract remains a valid zero-parameter capability. A successful Call does not extend schema or price metadata, and the plugin rebuilds business parameters from each model tool call.
• If the same tool appears under different exact queries in one session, the plugin does not guess which search_id to attach. The Call is rejected unless the caller explicitly sets allow_uncorrelated: true; the same opt-in is required for a known tool ID that was not discovered in the active context. The opt-in cannot bypass an expired known route or a missing known parameter contract.
• All state lives in the tool factory for the active OpenClaw context and is tied to its configured API key/base URL. Restart or recreate the context after credentials, endpoint, or authorization changes.
• A Call timeout, network failure, or server error is returned as an unknown execution outcome with retry_safe: false. A rate limit is also non-automatic-retry for paid single-submit semantics, without being mislabeled as executed. The agent must not repeat either automatically.

The output includes low-sensitivity discovery_cache hit/scope/match metadata so hosts can measure HTTP request reduction separately from model-visible tool-call reduction. This is exact-query session reuse, not fuzzy semantic routing or cross-session memory.

The native plugin manifest declares the same three names in contracts.tools, so current OpenClaw hosts can attribute and load the owning plugin before importing its runtime. Discover and Inspect are declared replay-safe; the paid Call tool is deliberately replay-unsafe.

Requirements

• Node.js >= 22.22.3 for the current stable OpenClaw host; the plugin package itself retains its Node.js >= 22.19.0 compatibility floor for older supported hosts
• OpenClaw >= 2026.6.11
• A QVeris API key — sign up at qveris.ai

Installation

From npm

openclaw plugins install @qverisai/qveris

From local source (development)

# From the repo root
openclaw plugins install -l ./packages/openclaw-qveris-plugin

Package safety checks

The published npm package is limited to runtime plugin files. Unit tests, integration tests, fixtures, helper scripts, and coverage output are intentionally excluded so normal installation does not require a security-audit override.

Before publishing, verify the package contents:

npm run build
npm pack --dry-run --json
npm run check:pack
npm run check:runtime
npm run check:runtime:packed

The package check instantiates the compiled factory with config, environment, and missing-credential cases. The runtime checks separately validate OpenClaw's registration contract and installed-package provenance in an isolated state directory. All checks use synthetic credentials and do not call the QVeris API. CI runs the host contract against the minimum supported host, the extended-stable host, and the latest stable host.

Real network integration tests must live under integration/ and are disabled by default:

QVERIS_RUN_INTEGRATION=1 npm run test:integration

Configuration

Add the following to your openclaw.json:

{
  // 1. Allow the plugin and make its tools visible to the agent
  plugins: {
    allow: ["qveris"],
    entries: {
      qveris: {
        enabled: true,
        config: {
          apiKey: "qv-your-api-key-here"  // or use QVERIS_API_KEY env var
        }
      }
    }
  },

  // 2. Add QVeris tools to the agent's tool allowlist
  tools: {
    alsoAllow: ["qveris"]
  }
}

Note: tools.alsoAllow is required. Without it, plugin tools are not passed to the LLM even though the plugin is loaded.

API key via environment variable

If you prefer not to store the key in the config file:

export QVERIS_API_KEY=qv-your-api-key-here

The plugin checks plugins.entries.qveris.config.apiKey first, then falls back to QVERIS_API_KEY.

To make the API endpoint explicit through the environment:

export QVERIS_BASE_URL=https://qveris.ai/api/v1

Security: if no API key is found at startup, all three tools are silently omitted — no error is thrown.

Full configuration reference

All fields under plugins.entries.qveris.config:

Endpoint selection

Endpoint precedence is deterministic:

1. plugins.entries.qveris.config.baseUrl
2. QVERIS_BASE_URL
3. https://qveris.ai/api/v1

API keys never change the endpoint. Overrides must be complete HTTP(S) URLs without credentials, whitespace, backslashes, query parameters, or fragments. Trailing slashes are removed.

The legacy region field is deprecated and rejected with migration guidance. Remove region; when the default endpoint is not correct for the site that issued your key, set baseUrl or QVERIS_BASE_URL to that site's API URL.

Minimal vs full config examples

Minimal (env var key)

export QVERIS_API_KEY=qv-...

{
  plugins: {
    allow: ["qveris"],
    entries: { qveris: { enabled: true } }
  },
  tools: { alsoAllow: ["qveris"] }
}

With full-content materialization enabled

{
  plugins: {
    allow: ["qveris"],
    entries: {
      qveris: {
        enabled: true,
        config: {
          apiKey: "qv-...",
          autoMaterializeFullContent: true,
          fullContentMaxBytes: 20971520,    // 20 MB
          fullContentTimeoutSeconds: 60,
          executeTimeoutSeconds: 120         // for slow image/video generation tools
        }
      }
    }
  },
  tools: { alsoAllow: ["qveris"] }
}

Verification

After restarting the gateway, verify the plugin is loaded and tools are registered:

# Restart gateway
openclaw gateway restart

# Inspect the loaded runtime, registered tools, and diagnostics
openclaw plugins inspect qveris --runtime --json

Expected JSON should include:

{
  "plugin": {
    "status": "loaded",
    "toolNames": ["qveris_discover", "qveris_call", "qveris_inspect"]
  },
  "diagnostics": []
}

plugin.toolNames and tools[].names describe the runtime registration contract; they do not prove that the credential-gated factory returned concrete tools for a particular agent turn.

Troubleshooting

Tools not visible to the agent

Make sure tools.alsoAllow: ["qveris"] is set. Without this, plugin tools are excluded from the tool list sent to the LLM even if the plugin is loaded.

Plugin loaded but tools missing from plugins inspect

First inspect the runtime:

openclaw plugins inspect qveris --runtime --json

If diagnostics report that contracts.tools is missing, upgrade @qverisai/qveris to 2026.7.30 or later and restart the Gateway. If the registration is present but the agent does not receive the tools, check the API key:

openclaw config get plugins.entries.qveris
# or
echo $QVERIS_API_KEY

plugin id mismatch warning on startup

Your npm package name must unscopе to match the plugin id qveris. The correct package name is @qverisai/qveris (not @qverisai/openclaw-qveris-plugin).

Cannot find module '@.../dist/plugin-sdk/root-alias.cjs/plugin-entry'

The OpenClaw host's dist/ is not built. Either:

• Use the official openclaw npm package as the host, or
• Run pnpm build in the OpenClaw fork before loading the plugin.

License

MIT