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:

The typical agent workflow is: qveris_discover → qveris_inspect (optional) → qveris_call.

Requirements#

• Node.js >= 22.19.0
• 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

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 plugin
openclaw plugins inspect qveris

Expected output should include:

Status: loaded
Tools:
qveris_discover, qveris_call, qveris_inspect

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#

The API key is not configured. Check:

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