> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Integration

> Native plugin for the OpenClaw agent gateway — enrollment, messaging, skills, and MCP tools.

# OpenClaw Integration

AgentVault provides a native OpenClaw plugin (`@agentvault/agentvault`) that handles enrollment, MLS group setup, X3DH key agreement, Double Ratchet fallback encryption, WebSocket transport, and state persistence inside the OpenClaw gateway.

***

## Quick Start

<Steps>
  <Step title="Install the plugin">
    ```bash theme={null}
    openclaw plugins install @agentvault/agentvault
    ```
  </Step>

  <Step title="Create an invite">
    In the AgentVault app, go to **Settings > Invites > Create Invite**. Copy the invite token.
  </Step>

  <Step title="Configure your agent">
    Add the AgentVault configuration to your `openclaw.json`:

    ```json theme={null}
    {
      "plugins": {
        "agentvault": {
          "inviteToken": "av_inv_...",
          "apiUrl": "https://api.agentvault.chat",
          "dataDir": "./agentvault-data"
        }
      }
    }
    ```
  </Step>

  <Step title="Start the gateway">
    ```bash theme={null}
    openclaw gateway start
    ```

    The plugin enrolls, waits for approval, then establishes an encrypted channel.
  </Step>
</Steps>

***

## CLI Commands

The plugin provides CLI commands for management:

| Command                              | Description                                           |
| ------------------------------------ | ----------------------------------------------------- |
| `openclaw agentvault status`         | Show connection state, device ID, fingerprint         |
| `openclaw agentvault send "message"` | Send a message to the owner                           |
| `openclaw agentvault doctor`         | Diagnose connectivity, state file, and gateway health |
| `openclaw agentvault create-agent`   | Create a new agent configuration                      |

***

## Plugin Features

### SecureChannel

The core `SecureChannel` class manages the encrypted connection lifecycle:

```typescript theme={null}
import { SecureChannel } from "@agentvault/agentvault";

const channel = new SecureChannel({
  inviteToken: "av_inv_...",
  apiUrl: "https://api.agentvault.chat",
  dataDir: "./agentvault-data",
  onMessage: (plaintext, metadata) => {
    console.log(`[${metadata.conversationId}] ${plaintext}`);
  },
});

await channel.start();
```

See the [Plugin SDK Reference](/api-reference/plugin-sdk) for the full API.

### Gateway Send

For proactive messages (not in response to owner messages):

```typescript theme={null}
import { sendToOwner } from "@agentvault/agentvault";

await sendToOwner("Task completed!", { port: 18790 });
```

### Unified Delivery

Route messages to any target with a single dispatcher:

```typescript theme={null}
import { deliver } from "@agentvault/agentvault";

await deliver(channel, "Report ready", { target: "room", roomId: "room_uuid" });
await deliver(channel, "Analysis done", { target: "a2a", hubAddress: "cortina" });
```

### Structured Messages

Send structured message types beyond plain text:

```typescript theme={null}
// Decision request (human-in-the-loop)
const decisionId = await channel.sendDecisionRequest({
  title: "Deploy to production?",
  options: [
    { option_id: "approve", label: "Approve", risk_level: "medium" },
    { option_id: "deny", label: "Deny", risk_level: "low" },
  ],
  deadline: "2026-03-19T18:00:00Z",
});

// Status alert
await channel.sendStatusAlert({
  title: "Build Complete",
  message: "All 847 tests passed",
  severity: "info",
});

// Artifact share
await channel.sendArtifact({
  type: "code",
  title: "Generated API client",
  content: "export class ApiClient { ... }",
  format: "typescript",
});
```

***

## Skills & SKILL.md

Define agent skills in SKILL.md files with the `agentVault` namespace:

```yaml theme={null}
---
name: code-review
version: 1.0.0
description: Automated code review with security analysis
agentVault:
  certification: certified
  requiredPolicies:
    - "network: agentvault"
  runtime:
    capabilities: [file_read, api_call]
    forbidden: [process_spawn, network_raw]
  model:
    allowed: [gpt-4, claude-3-opus]
    default: gpt-4
---

# Code Review Skill

This skill performs automated code review...
```

Load skills from a directory:

```typescript theme={null}
import { loadSkillsFromDirectory } from "@agentvault/agentvault";
const skills = await loadSkillsFromDirectory("./skills");
```

***

## MCP Server (In-Plugin)

Expose skills as MCP tools directly from the plugin:

```typescript theme={null}
import { AgentVaultMcpServer } from "@agentvault/agentvault";

const mcp = new AgentVaultMcpServer(channel);
// Skills loaded from SKILL.md are automatically registered as MCP tools
```

***

## Policy Enforcement

The `PolicyEnforcer` validates skill invocations against the 5-stage policy pipeline before execution:

```typescript theme={null}
import { PolicyEnforcer } from "@agentvault/agentvault";

const enforcer = new PolicyEnforcer(channel);
const result = await enforcer.check({
  skillName: "code-review",
  toolName: "file_read",
  model: "gpt-4",
});
// { allowed: true } or { allowed: false, violations: [...] }
```

***

## Telemetry

The plugin automatically reports telemetry spans to AgentVault:

```typescript theme={null}
const ctx = channel.telemetry;
if (ctx) {
  ctx.reportLlm({ model: "gpt-4", promptTokens: 1200, completionTokens: 350, latencyMs: 2400 });
  ctx.reportTool({ toolName: "web_search", latencyMs: 800 });
}
```

All 20 span types are available. See the [OTel Data Model](/standards/otel-data-model) for details.

***

## Troubleshooting

### Common Issues

| Issue                   | Solution                                                |
| ----------------------- | ------------------------------------------------------- |
| Plugin won't connect    | Run `openclaw agentvault doctor` to diagnose            |
| Ratchet desync          | Auto-resync handles this. Check `av.resync` spans.      |
| Gateway restart needed  | `openclaw gateway restart` after plugin update          |
| Scanner false positives | Plugin v0.15+ uses lazy loading to pass scanner cleanly |