AgentKV 技能
AgentKV 是一个面向代理的原生键值存储。你持有一个 AgentKV 账户，可通过以下两种方式之一持有（客户端自动检测）——相同的数据、相同的信用、相同的零知识加密：
- 钱包即密钥（默认）：可签名的钱包就是账户。其地址是命名空间，其密钥派生 AES 密钥。AgentKV 在首次使用时自动预配一个钱包——无需账户、无需 API 密钥、无需注册。
- 账户密钥：对于无法签名的托管钱包（例如 awal），一个不透明的
ak_…承载令牌充当身份和命名空间，一个本地加密密钥进行加密——与付费钱包解耦，因此任何签名钱包都可以为此账户充值。
值在到达服务器之前已在客户端加密（AES-256-GCM），因此服务器是零知识的。存储消耗 Base（主网）或 Base Sepolia（测试网）上的真实 USDC，通过 x402 协议按操作收费。
前提条件：
@agentkv/cli必须已发布到 npm 并可通过npx @agentkv/cli解析。截至本文撰写时，该包尚未发布——此插件是等待发布步骤的产物。
何时使用 AgentKV
在以下情况下使用 AgentKV：
- 跨会话持久内存——事实、偏好、摘要或任务状态，必须在当前会话结束时仍然存在。
- 秘密存储和使用——API 密钥、令牌或凭据。服务器仅能看到密文（零知识）。⚠️ 普通的
agentkv_set/agentkv_get会将值路由到此代理的模型上下文中；对于真正的秘密，请使用秘密安全工具（agentkv_set_from_env/_from_file进行存储，agentkv_get_to_file/agentkv_run_with_secret进行使用），这样明文永远不会进入模型轮次。请参阅下面的秘密部分。 - 共享集群状态——多个共享同一钱包的代理实例可以通过一个公共命名空间进行协调（例如，任务队列、锁、共享计数器）。
- TTL 限定的临时状态——具有自动过期功能的临时值（例如，nonce、草稿），这样你就无需手动清理。
请勿将 AgentKV 用于：
- 大型二进制文件（最大值大小为 256 KB）。
- 在预算敏感环境中的免费、零成本操作——每次
set和get都消耗 USDC；请先检查消费上限。 - 替代面向用户应用程序中的合适数据库（它专为代理工作负载设计，而非高吞吐量的 Web 应用）。
可用的 MCP 工具
agentkv MCP 服务器公开了十二个工具——八个核心工具，加上四个秘密安全工具，其明文永远不会进入模型上下文（请参阅下面的秘密部分）：
| 工具 | 描述 | 成本 |
|---|---|---|
agentkv_set | 在密钥下写入一个加密值。接受可选的 TTL（天）。 | ~$0.005 USDC |
agentkv_get | 按密钥读取并解密一个值。默认情况下，滑动 TTL 会重置过期时间。 | ~$0.003 USDC |
agentkv_delete | 立即删除一个密钥。 | 免费 |
agentkv_deposit | 向钱包的命名空间存入 USDC 信用以预付费操作。在账户密钥模式下被拒绝（托管账户没有钱包——通过 <endpoint>/account/deposit 为其充值）。 | 购买 USDC |
agentkv_balance | 检查钱包命名空间当前的 USDC 信用余额。 | 免费 |
agentkv_wallet_address | 返回钱包地址（命名空间标识符）。信息性。 | 免费 |
agentkv_fund | 返回一个卡→USDC 入金 URL，将 USDC 交付至 Base 上的钱包。仅构建 URL——不进行支付。在账户密钥模式下被拒绝（没有钱包可以购买 USDC）。 | 免费 |
agentkv_list_keys | 列出此钱包存储的密钥——真实的密钥名称，在本地解密；服务器仅能看到不透明的摘要。分页。 | 免费 |
agentkv_set_from_env | 存储从本地环境变量读取的秘密（传递变量名称）。值永远不会进入模型上下文。 | ~$0.005 USDC |
agentkv_set_from_file | 存储从本地文件读取的秘密（传递路径）。内容永远不会进入模型上下文。 | ~$0.005 USDC |
agentkv_get_to_file | 将值解密到本地文件；返回 { found, path, bytes }——绝不返回值。 | ~$0.003 USDC |
agentkv_run_with_secret | 运行一个命令，秘密仅注入到子进程的环境变量中；返回命令的输出，绝不返回秘密。 | ~$0.003 USDC |
定价和存款： 即用即付约 $0.005/次
agentkv_set，约 $0.003/次agentkv_get。预付费信用的成本大约为1/10（约 $0.0005/次 set，约 $0.0003/次 get）。agentkv_deposit需要 $1.00 最低金额，并以折扣信用率为命名空间充值。
秘密——将值保留在模型上下文之外
agentkv_set 和 agentkv_get 将值路由到此代理自身的模型上下文中（写入时是工具参数，读取时是工具结果）。客户端加密使值对服务器零知识——但它不会对代理隐藏值。因此，普通的 set/get 适用于非秘密内存（计划、摘要、偏好），但对于真正的凭据，请使用秘密安全工具，使明文永远不会进入模型轮次：
- 存储：
agentkv_set_from_env（传递环境变量名称）或agentkv_set_from_file（传递路径）。服务器在本地读取值，加密并存储。 - 使用：
agentkv_run_with_secret（运行一个命令，秘密仅注入到子进程的环境变量中，并返回命令的输出）或agentkv_get_to_file（将解密后的值写入本地文件并返回路径——使用后删除）。
残留：秘密会短暂地出现在本地文件或子进程环境变量中——本地且短暂，绝不会发送到模型提供商或写入对话历史。agentkv_run_with_secret（不涉及磁盘文件）是最严格的。
一次性设置
从 Claude Code 的市场安装插件——确切的 /plugin marketplace add 和 /plugin install 命令在插件的 README.md（plugin/README.md）中。安装后：
1. 凭据（安装时输入，而非通过 shell 环境变量）
安装插件时，Claude Code 会提示输入以下内容，并将它们注入 MCP 服务器（私钥被屏蔽并存储在操作系统的钥匙串中——绝不会写入磁盘）：
| 配置 | 必需 | 描述 |
|---|---|---|
| 钱包私钥 | 否 | 可选——留空，AgentKV 将在首次使用时生成并管理一个本地钱包（然后充值并备份）。要自带：一个 EVM 私钥（十六进制），即付费和拥有命名空间的钱包。 |
| AgentKV 端点 | 否 | 托管的 AgentKV API；默认为 https://api.agentx402.ai。 |
| 网络 | 否 | eip155:8453（Base 主网，默认）或 eip155:84532（Base Sepolia 测试网）。 |
| 加密密钥 | 否 | 覆盖派生的 AES 密钥（高级；默认使用来自私钥的 HKDF）。 |
| 单次操作最大消费（USD） | 否 | 拒绝任何超过此成本的单次操作；空值 = 无每次操作上限。 |
| 会话最大消费（USD） | 否 | 一旦累计会话消费超过此值，拒绝操作；空值 = 无上限。 |
稍后运行 /plugin 可更改这些设置。通过 /mcp 验证服务器已加载（你应该能看到 agentkv 服务器及其十二个工具）。
要使用卡而非现有 USDC 余额充值，agentkv_fund 工具会返回一个 Coinbase 入金 URL——通过在服务器上设置 AGENTKV_ONRAMP_APP_ID（一个公共 CDP 项目 ID）来配置它，并可选择设置 AGENTKV_ONRAMP_PROVIDER 以切换提供商。
2. 为命名空间充值
使用 agentkv_wallet_address 读取你的钱包地址，向它在 Base 上发送 USDC（或调用 agentkv_fund 获取一个卡→USDC 入金 URL，将 USDC 交付到该地址），然后调用 agentkv_deposit 并传入一个金额（最低 $1）来为命名空间充值。读取和写入将自动从信用中支付。
账户密钥模式（托管钱包 / awal）
无法签名的托管钱包使用账户密钥模式而非钱包。在插件之外，CLI 会生成并充值一个账户：
agentkv account new # 生成 ak_… 和一个本地加密密钥（保存为 0600 权限）——请备份它们，不可恢复
# 从任意签名钱包为其充值（首次存款时，真正的 ≥$1 存款会创建账户）：
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'
然后设置 AGENTKV_ACCOUNT_KEY=ak_… 和 AGENTKV_ENCRYPTION_KEY=0x…（本地 AES 密钥——在账户模式下必需，因为没有钱包可以派生密钥）。账户即命名空间；默认情况下，读取/写入仅携带承载令牌并从预付信用中扣款——无需每次操作签名。无论哪种方式，它对服务器都是零知识的。任何签名钱包都可以为同一个账户充值。
如果同时设置了 AGENTKV_TOPOFF=awal，信用不足时会自动修复——无需操作，CLI/MCP 会话通过 awal 支付自己的补款并继续。如果未设置，在信用不足错误时运行 awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' 并重试。或者，设置 AGENTKV_INLINE=awal 以按操作内联支付：每个请求会随承载令牌一起携带支付签名，并立即在链上结算，因此根本不需要预付信用。
消费上限意识
每次 agentkv_set、agentkv_get 和 agentkv_deposit 调用都会消耗真实的 USDC（agentkv_delete、agentkv_balance、agentkv_wallet_address、agentkv_fund 和 agentkv_list_keys 是免费的）。在开始循环或批量操作之前：
- 调用
agentkv_balance确认有足够的信用。 - 在插件配置中设置**单次操作最大消费（USD）和/或会话最大消费（USD）**上限（运行
/plugin进行编辑）。 - 如果工具调用返回 402 Payment Required 错误且没有剩余消费预算，则暂停并向用户报告，而不是盲目重试。
当信用耗尽时，服务器会返回一个 PAYMENT-REQUIRED 挑战；CLI 会在消费上限内自动处理 x402 支付。
共享集群状态模式
当多个代理共享同一个 AGENTKV_PRIVATE_KEY（相同钱包 = 相同命名空间）时，它们可以通过约定好的密钥进行协调：
fleet:lock:<task-id> # 分布式锁（使用短 TTL 设置）
fleet:queue # 序列化的任务列表
fleet:result:<task-id> # 已完成的子任务的输出
在锁上使用短 TTL 以防止代理崩溃时出现陈旧的持有。
密钥命名约定
- 使用
:作为分隔符：session:<id>:summary、secret:github-token、prefs:language。使用秘密安全工具（agentkv_set_from_env/_from_file、agentkv_get_to_file/run_with_secret）存储/读取secret:*密钥——绝不使用普通的set/get——这样凭据就不会进入模型上下文。 - 使用稳定的标识符作为用户特定数据的前缀：
user:<handle>:...。 - 在写入共享集群状态之前，使用
agentkv_wallet_address确认你正在操作的命名空间。