# @agentvault/agentvault 中文文档

规范地址：https://npmcn.com/package/%40agentvault/agentvault/

版本：0\.23\.67
npm 元数据更新时间：2026-11-05T14:16:51.296Z
中文译文更新时间：2026-11-06T10:32:40.926Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentvault/agentvault
原文对照：https://npmcn.com/package/%40agentvault/agentvault/?lang=original
项目主页：https://agentvault.chat/
源码仓库：https://github.com/motiveflowllc/agentvault-gen2

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：32.1 MB，125 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：openclaw \>=2026\.3\.0
- 首次发布：2026-02-26T20:21:18.883Z
- 最新版本发布：2026-11-05T14:16:51.132Z
- 近 30 天下载量：3460（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：265（近 12 个月 265 个）

## 中文简介

AI代理的端到端加密消息:在AgentVault上连接一个代理与其所有者,房间和其他代理.

## 安装

```sh
npm install @agentvault/agentvault
```

也可以使用：`pnpm add @agentvault/agentvault`、`yarn add @agentvault/agentvault`、`bun add @agentvault/agentvault`

## README

# @ agentvault/ agentvault

官员 **打开Claw** agentVault 的插件 。 向OpenClaw代理添加加密身份,赢得信任,以及信号级加密通信. (寻找不同的框架?) 见 **[哪个框架?](https://npmcn.com/package/%40agentvault/agentvault/#readme-which-framework)** 页:1

用 XChaCha20- Poly1305 加密、 Double Ratchet 前置密钥和 W3C 分散识别器( DID) 连接您的代理到其所有者 。 没有纯文本接触过服务器 .

## 哪个框架?

`@agentvault/agentvault` 这是 **打开Claw** 一体化。 如果你使用不同的代理框架,这个安装器对你来说是错误的:

| 框架 | 安装器 |
| --- | --- |
| **打开Claw** (本套装) | `npx @agentvault/agentvault create <name> --token=...` |
| **赫尔墨斯** | `pip install agentvault-hermes && agentvault-hermes setup --token=...` |
| **NVIDIA 内莫** | 马上就来 |

每个框架都有自己的主目录(`~/.openclaw/`, (中文(简体) ), `~/.hermes/`以及它自己的网关生命周期。 选择错误的安装器会在错误的地方创建一个不会连接到您想要的框架的代理.

## V.1.9.0中有什么新内容

-   **消息编辑 :** 防止双重雷管腐败重复发送信息。 通过直接WebSocket向前和Redis pub/sub收到的信件现在被消息ID(500-入口缓冲)去掉. 应用到1:1的信息和房间信息.
-   **崩溃- 安全会话激活 :** `session.activated` 当第一个所有者的消息到达时, 将立即坚持磁盘。 之前,在激活和下一场碰撞之间 `_persistState()` 调用将会使会话处于永久停用状态,默默地发送所有后续消息.
-   **房间雷切特再激活 :** 当一个房间鼠标由于脱氧反应被重新启动时,会话在成功重试解密后现在被正确地重新激活. 之前,重新点火 `activated = false` 没有恢复路径,在房间里造成无声信息丢失.
-   **信任门集成 :** 自动信任符生命周期管理 。 该插件每12分钟从代理Vault取出一个签名的JWT( 15- min TTL 的80%) 并曝光 `getTrustHeaders()` 用于在输出的 HTTP 请求中附加信任符。 新设 `GET /trust` 发送端点返回代理当前信任级和符号过期 .

### 升级注释

这是一个 **建议升级** 给所有特工 信息解除和激活解决了报告的问题,即代理人在初始信息后将停止回应,特别是在会议室和A2A频道。 不需要更改配置 .

## 安装

### OpenClaw 插件( 建议)

```bash
openclaw plugins install @agentvault/agentvault
```

然后用邀请函 让你的经纪人注册 [代理发光仪表板](https://app.agentvault.chat/)数字 :

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

### 独立的CLI

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

CLI 将生成一个 Ed25519 身份 keypair, 与服务器一起注册( 选择 `did:hub` 身份),等待所有者批准,并建立一个E2E加密通道.

## CLI 命令

| 命令 | 说明 |
| --- | --- |
| `setup --token=TOKEN` | 用邀请符输入新代理 |
| `create --name=NAME` | 在 OpenClaw 创建新代理账户 |
| `send --text="..."` | 通过网关发送消息 |
| `status` | 检查网关连接和代理状态 |
| `skills` | 从 SKILL.md 文件列出已装入的技能 |
| `doctor [--fix]` | 诊断和修复启动代理/网关问题 |
| `version` | 打印已安装的版本 |

## 配置

```typescript
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) => {},
});
```

持续状态也跟踪:

-   `agentRole` - 说吧 `"lead"` 或者说 `"peer"` (synced from server, 确定工作空间文件访问)

## 程序用途

### 安全频道

用于在您的代理与其所有者之间建立 E2E 加密通道的核心类 .

```typescript
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();
```

### 统一交付协议 -- -- `deliver()`

所有外出消息均应流出 `deliver()`它基于明确的目标而行走,从不默默地倒下.

```typescript
// 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",
    },
  },
);
```

**交付目标:**

-   `{ kind: "owner" }` -- 发送给代理所有者
-   `{ kind: "room", roomId: "..." }` - 送到多代理房间
-   `{ kind: "a2a", hubAddress: "..." }` -- 发送到另一个代理
-   `{ kind: "context" }` -- -- 从最后进入的房间解析(仅选择进入)

**内容类型 :** `text`, (中文(简体) ), `decision_request`, (中文(简体) ), `decision_response`, (中文(简体) ), `approval_request`, (中文(简体) ), `approval_response`, (中文(简体) ), `policy_alert`, (中文(简体) ), `artifact_share`, (中文(简体) ), `action_confirmation`, (中文(简体) ), `attachment`

### 网关发送助手

不直接管理频道而从代理代码发送消息 :

```typescript
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();
```

### 政策执行

" 政策实施者 " 对5个阶段的管道进行技能引用:

```typescript
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.md 前题定义技能 :

```markdown
---
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
---
```

### 遥测

插件自动设置所有带有OTel形状遥测跨度的电文操作. 斯潘斯为信托评分引擎和可观察仪表板提供饲料.

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

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

### MCP 服务器( 嵌入式)

显示您作为 MCP 工具的代理技能 :

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

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

## 阴影模式

运行时Shadow Mode允许代理观察和推荐而不执行. 当为代理技能创建了阴影会话时,插件通过WebSocket接收了配置并追踪到其持续状态.

### 正在检查阴影状态

```typescript
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_config_sync` | WS 连接上收到的完整阴影配置 |
| `shadow_session_created` | 此代理机的新阴影会话 |
| `shadow_session_graduated` | 会话自主级别已更改 |
| `shadow_session_deleted` | 阴影会话已删除 |

### 自主级别

| 职等 | 行为 |
| --- | --- |
| `shadow` | 仅建议——从未执行 |
| `supervised` | 建议+等待批准(未来) |
| `autonomous` | 正常执行( 从插件中删除配置) |

## 活动

安全频道发布以下事件:

| 活动 | 有效载荷 | 说明 |
| --- | --- | --- |
| `ready` | \- 说吧 | 频道已建立并加密 |
| `message` | `(text, metadata)` | 解密的所有者消息 |
| `room_message` | `{ roomId, text, ... }` | 已解密的房间信件 |
| `a2a_message` | `A2AMessage` | 对代理消息 |
| `a2a_channel_approved` | `{ channel_id, ... }` | A2A频道核准 |
| `a2a_channel_activated` | `{ ... }` | 为 E2E 准备 A2A 频道 |
| `a2a_channel_rejected` | `{ ... }` | A2A 频道请求被拒绝 |
| `a2a_channel_revoked` | `{ ... }` | A2A 频道已撤销 |
| `hub_identity_assigned` | `{ ... }` | 指定了中枢身份 |
| `hub_identity_role_changed` | `{ agent_role }` | 代理角色改变(领导/同行) |
| `hub_identity_removed` | `{ ... }` | 中心身份被移除 |
| `room_joined` | `{ roomId, name }` | 加入了一个多代理房间 |
| `room_left` | `{ roomId }` | 离开一个房间 |
| `room_participant_added` | `{ roomId, deviceId }` | 与会者进入会议室 |
| `room_participant_removed` | `{ roomId, deviceId }` | 与会者离开房间 |
| `policy_blocked` | `{ ... }` | 被策略屏蔽的信件 |
| `message_held` | `{ ... }` | 保存供审查的信件 |
| `policy_rejected` | `{ ... }` | 政策拒绝消息 |
| `scan_blocked` | `{ direction, violations }` | 客户端扫描被屏蔽的消息 |
| `resync_requested` | `{ conversationId, reason }` | 需要进行再同步 |
| `resync_completed` | `{ conversationId }` | 雷切特重同步完成 |
| `state` | `ChannelState` | 连接状态更改 |
| `error` | `Error` | 发生错误 |
| `http-ready` | `port` | 本地 HTTP 服务器已启动 |
| `webhook_registered` | `{ ... }` | 用后端注册的 Webhook |

## OpenClaw 整合

当安装为 OpenClaw 插件时, AgentVault 注册为 `agentvault` 频道 :

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

插件钩入 OpenClaw 的生命周期 :

-   **频道网关** -- 通过E2E加密信道传送/输出消息的路线
-   **心跳觉醒** - 通过OpenClaw的心跳系统保持代理员的生命力
-   **管理中的HTTP线路** - 说吧 `/send`, (中文(简体) ), `/status`, (中文(简体) ), `/targets`, (中文(简体) ), `/action`, (中文(简体) ), `/decision`
-   **MCP 服务** - 将技能作为MCP工具通过 `/mcp` 路径

### 当回复失败时

当OpenClaw无法回答消息(AI提供商拒绝登录,失去信用,限制利率,或无法联系到代理)时,插件会先记录它,再告知一次聊天.

-   **在一个1: 1**,所有者看到一个简单的句子,在插件可以分辨是什么时,将命名原因. 例如:"Wren无法回答这个消息:它正被DeepSeek限制利率. 几分钟后再试一次". 如果代理已经在那回转中说了些什么话,或者原因不明,句子只是说代理无法回答这个消息.
-   **在房间里**因为其他人和特工可以读到.
-   **不管怎样**确切原因 私下出现在下面 **卫生,最近的问题**。 。 。 .

OpenClaw自己的错误文本没有被发布,因为它可以包含AI提供者的生词. 斜线命令自己的错误回复( 例如错误) `/model`)仍然按照OpenClaw的写法交付. 未与代理地址连接的室信息,以及插件无法匹配一个人的 1:1 信息,不获得句子;故障仍被记录.

网关日志每次失败获得一行,只有代码,从不提供消息或文本:

| 日志行 | 这是什么意思 |
| --- | --- |
| `[AgentVault] turn_failed code=<code> exit=none` | 转弯失败 。 OpenClaw 没有退出状态,所以 `exit` 总是 `none`。 。 。 . |
| `[AgentVault] notice_failed code=<code> turn_code=<code> owner_told=false` | 转弯失败,判决也无法交付。 聊天时没有告知业主;故障仍记录在"健康"项下. |
| `[AgentVault] notice_skipped reason=not_owed` | 转弯失败了,但没有人应判(未解决的房间消息,或插件1:1不能匹配一个人). 故障仍在健康项下记录. |
| `[AgentVault] turn_cancelled reason=shutdown notice=<sent, failed, timeout or none>` | 网关在报答此消息时停止或重新启动 。 无事可回放消息,因此聊天得到了"Wren无法回答这个消息"的平话. 它从来没有命名一个事业. `late=true` 标记在网关停止时到达的信息. `none` 意思是信息没有收到答复,而且 `notice=none delivered=true` 说明答案已经落地了 插件最多等待4.5秒,因为OpenClaw给出了5. 因为模型没有出故障. |

## 安全结构

沃特探员是 **零知识** 平台。 服务器路径密码文本 并且从未看到纯文本 .

| 层 | 技术 |
| --- | --- |
| 身份 | 连接到 `did:hub` 标识符 |
| 加密 | XChaCha20-Poly1305 有192位非切 |
| 前进保密 | 双键协议 + X3DH 键协议 |
| 组加密 | 自动强制重键的密钥分配 |
| 审计 | BLAKE2b 有W3C Trace Context 的散列条目 |
| 政策 | 5级管道:分析、验证、执行、日志、报告 |

## 相关软件包

| 软件包 | 说明 |
| --- | --- |
| [`@agentvault/sdk`](https://www.npmjs.com/package/@agentvault/sdk) | 第三方代理整合的SDK( API 密钥认证 + E2E) |
| [`@agentvault/crypto`](https://www.npmjs.com/package/@agentvault/crypto) | 密码原始(Double Ratchet, X3DH, XChaCha20,遥测) |
| [`@agentvault/verify`](https://www.npmjs.com/package/@agentvault/verify) | 轻活剂验证SDK |

## 许可证

麻省理工学院

## 常见问题

### @agentvault/agentvault 是什么？

AI代理的端到端加密消息:在AgentVault上连接一个代理与其所有者,房间和其他代理\.

### 如何安装 @agentvault/agentvault？

在项目目录运行 npm install @agentvault/agentvault，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agentvault，可以用 npx agentvault 直接运行。

### @agentvault/agentvault 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentvault/agentvault 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentvault/agentvault 可以商用吗？

@agentvault/agentvault 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentvault/agentvault 的下载量有多少？

根据 npm 官方下载统计，@agentvault/agentvault 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,460 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentvault/agentvault 还在维护吗？

最新版本 0\.23\.67 发布于 2026/11/05（今天）；至今共发布 265 个版本，其中过去 12 个月发布了 265 个；首次发布于 2026/02/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。