@agentvault/agentvault

The official OpenClaw plugin for AgentVault. Adds cryptographic identity, earned trust, and Signal-grade encrypted communications to OpenClaw agents. (Looking for a different framework? See Which Framework? below.)

Connect your agent to its owner with XChaCha20-Poly1305 encryption, Double Ratchet forward secrecy, and W3C Decentralized Identifiers (DIDs). No plaintext ever touches the server.

Which Framework?

@agentvault/agentvault is the OpenClaw integration. If you're using a different agent framework, this is the wrong installer for you:

Each framework has its own home directory (~/.openclaw/, ~/.hermes/, etc.) and its own gateway lifecycle. Picking the wrong installer creates an agent in the wrong place that won't connect to the framework you intended.

What's New in v0.19.0

• Message Dedup: Prevents Double Ratchet corruption from duplicate message delivery. Messages received via both direct WebSocket forward and Redis pub/sub are now deduplicated by message ID (500-entry buffer). Applies to 1:1 messages and room messages.
• Crash-Safe Session Activation: session.activated is now persisted to disk immediately when the first owner message arrives. Previously, a crash between activation and the next _persistState() call would leave the session in a permanently deactivated state, silently dropping all subsequent messages.
• Room Ratchet Re-Activation: When a room ratchet is re-initialized due to desync, the session is now correctly re-activated after successful retry decrypt. Previously, re-init set activated = false with no recovery path, causing silent message loss in rooms.
• Trust Gate Integration: Automatic trust token lifecycle management. The plugin fetches a signed JWT from AgentVault every 12 minutes (80% of 15-min TTL) and exposes getTrustHeaders() for attaching trust tokens to outbound HTTP requests. New GET /trust delivery endpoint returns the agent's current trust tier and token expiry.

Upgrade Notes

This is a recommended upgrade for all agents. The message dedup and activation fixes resolve reported issues where agents would stop responding after initial messages, particularly in rooms and A2A channels. No configuration changes required.

Installation

OpenClaw Plugin (Recommended)

openclaw plugins install @agentvault/agentvault

Then enroll your agent with an invite token from the AgentVault dashboard:

npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN

Standalone CLI

npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN
npx @agentvault/agentvault

The CLI will generate an Ed25519 identity keypair, enroll with the server (anchoring a did:hub identity), wait for owner approval, and establish an E2E encrypted channel.

CLI Commands

Configuration

const channel = new SecureChannel({
  // Required
  inviteToken: process.env.AGENTVAULT_INVITE_TOKEN,
  dataDir: "./agentvault-data",
  apiUrl: "https://api.agentvault.chat",

  // Optional
  agentName: "My Agent",
  agentVersion: "1.0.0",
  httpPort: 18790,           // Local HTTP port for unified delivery protocol
  enableScanning: true,      // Enable client-side policy scanning
  backupCode: "...",         // Auto-backup encrypted state to server

  // Callbacks
  onMessage: (text, metadata) => {},
  onStateChange: (state) => {},
  onA2AMessage: (msg) => {},
  onA2AChannelReady: (info) => {},
});

The persisted state also tracks:

• agentRole -- "lead" or "peer" (synced from server, determines workspace file access)

Programmatic Usage

SecureChannel

The core class for establishing an E2E encrypted channel between your agent and its owner.

import { SecureChannel } from "@agentvault/agentvault";

const channel = new SecureChannel({
  inviteToken: process.env.AGENTVAULT_INVITE_TOKEN,
  dataDir: "./agentvault-data",
  apiUrl: "https://api.agentvault.chat",
  agentName: "My Agent",
});

channel.on("message", (text, metadata) => {
  console.log(`Owner says: ${text}`);
  console.log(`Type: ${metadata.messageType}`);
});

channel.on("ready", () => {
  console.log(`Secure channel established: did:hub:${channel.deviceId}`);
});

await channel.start();

Unified Delivery Protocol -- deliver()

All outbound messages should flow through deliver(). It routes based on explicit target and never silently falls back.

// Send to the agent owner
await channel.deliver(
  { kind: "owner" },
  { type: "text", text: "Task complete" },
);

// Send to a multi-agent room
await channel.deliver(
  { kind: "room", roomId: "room_abc123" },
  { type: "text", text: "Ready for review" },
);

// Send to another agent (A2A)
await channel.deliver(
  { kind: "a2a", hubAddress: "did:hub:other_agent" },
  { type: "text", text: "Handoff data" },
);

// Send a decision request
await channel.deliver(
  { kind: "owner" },
  {
    type: "decision_request",
    request: {
      question: "Which database?",
      options: [
        { label: "PostgreSQL", value: "postgres" },
        { label: "SQLite", value: "sqlite" },
      ],
      urgency: "medium",
    },
  },
);

Delivery targets:

• { kind: "owner" } -- Send to the agent owner
• { kind: "room", roomId: "..." } -- Send to a multi-agent room
• { kind: "a2a", hubAddress: "..." } -- Send to another agent
• { kind: "context" } -- Resolve from last inbound room (opt-in only)

Content types: text, decision_request, decision_response, approval_request, approval_response, policy_alert, artifact_share, action_confirmation, attachment

Gateway Send Helpers

Send messages from your agent code without managing the channel directly:

import { sendToOwner, sendToRoom, sendToTarget, listTargets } from "@agentvault/agentvault";

await sendToOwner("Task complete -- 3 files processed");
await sendToRoom("room_abc123", "Ready for review");
await sendToTarget("did:hub:other_agent", "Handoff data");

const targets = await listTargets();

Policy Enforcement

The PolicyEnforcer validates skill invocations against a 5-stage pipeline:

import { PolicyEnforcer } from "@agentvault/agentvault";

const enforcer = new PolicyEnforcer();

enforcer.registerSkill({
  name: "code-review",
  toolsAllowed: ["file.read"],
  toolsDenied: ["shell.exec", "network.raw"],
  modelRouting: { allowed: ["gpt-4", "claude-sonnet-4-20250514"] },
});

const result = enforcer.evaluate({
  skillName: "code-review",
  toolName: "shell.exec",
  model: "gpt-4",
});

if (!result.allowed) {
  console.log("Blocked:", result.violations);
}

const metrics = enforcer.getMetrics();

Skill Management

Define skills using SKILL.md frontmatter:

---
name: code-review
version: "1.0.0"
description: Reviews code for issues
tags: [code-review, typescript]
sla:
  p95_latency_ms: 5000
  max_error_rate: 0.05
agentVault:
  certification: certified
  integrity:
    algorithm: XChaCha20-Poly1305
    hashChain: SHA-256
  requiredPolicies: ["network: agentvault"]
  runtime:
    capabilities: [file.read, web.fetch]
    forbidden: [shell.exec]
  model:
    allowed: [gpt-4, claude-sonnet-4-20250514]
    default: claude-sonnet-4-20250514
---

Telemetry

The plugin auto-instruments all message operations with OTel-shaped telemetry spans. Spans feed the trust scoring engine and observability dashboard.

import { wrapSkillExecution } from "@agentvault/agentvault";

const result = await wrapSkillExecution("code-review", async () => {
  return { issues: 3 };
});

MCP Server (Embedded)

Expose your agent's skills as MCP tools:

import { AgentVaultMcpServer } from "@agentvault/agentvault";

const mcpServer = new AgentVaultMcpServer({
  skills: manifest.skills,
  channel,
  enforcer,
});

Shadow Mode

Runtime Shadow Mode lets agents observe and recommend without executing. When a shadow session is created for an agent's skill, the plugin receives the config via WebSocket and tracks it in persisted state.

Checking Shadow Status

const shadow = channel.getShadowConfig("triage_ticket");
if (shadow) {
  // Skill is in shadow/supervised mode — send recommendation instead of executing
  const recommendation = await runLLMPipeline(input);
  await channel.deliver({
    type: "shadow_recommendation",
    recommendation: {
      sessionId: shadow.sessionId,
      skillName: "triage_ticket",
      decisionClass: shadow.decisionClass,
      recommendedAction: recommendation,
      observationId: observationId, // from POST /shadow/sessions/{id}/observations
    },
  });
} else {
  // Normal execution
  await executeAction(input);
}

Shadow Events

Autonomy Levels

Events

The SecureChannel emits the following events:

OpenClaw Integration

When installed as an OpenClaw plugin, AgentVault registers as the agentvault channel:

{
  "channels": {
    "agentvault": {
      "accountId": "your-agent-account-id"
    }
  }
}

The plugin hooks into OpenClaw's lifecycle:

• Channel gateway -- routes inbound/outbound messages through the E2E encrypted channel
• Heartbeat wake -- keeps the agent alive via OpenClaw's heartbeat system
• Managed HTTP routes -- /send, /status, /targets, /action, /decision
• MCP serving -- exposes skills as MCP tools via /mcp route

When a reply fails

When OpenClaw can't answer a message (the AI provider refused the sign-in, ran out of credit, rate-limited the agent, or could not be reached), the plugin records it first and then tells the chat once.

• In a 1:1, the owner sees one plain sentence that names the cause when the plugin can tell what it is. For example: "Wren couldn't answer this message: it is being rate-limited by DeepSeek. Try again in a few minutes." If the agent already said something in that turn, or the cause is unclear, the sentence just says the agent couldn't answer this message.
• In a room, the sentence never names the cause, because other people and agents can read it.
• Either way, the exact cause appears privately under Health, Recent problems.

OpenClaw's own error text is not posted, because it can contain the AI provider's raw words. A slash command's own error reply (for example a bad /model) is still delivered as OpenClaw wrote it. A room message that did not address the agent, and a 1:1 message the plugin cannot match to a person, get no sentence; the failure is still recorded.

The gateway log gets one line per failure, with codes only and never message or provider text:

Security Architecture

AgentVault is a zero-knowledge platform. The server routes ciphertext and NEVER sees plaintext.

Related Packages

License

MIT