agent-wallet

核心用法

agent-wallet 是一款专为 AI 代理设计的自托管比特币闪电网络钱包，由 MoneyDevKit 开发。该工具基于 BIP39 助记词实现完全自托管，无需 API 密钥或账户注册。通过单条命令即可完成初始化，自动生成 12 词助记词并派生钱包 ID，同时启动本地守护进程（localhost:3456）处理所有闪电网络操作。

主要功能包括：

• 余额查询：实时查看钱包余额（以 satoshis 为单位）
• 收款：支持固定金额发票、可变金额发票、BOLT12 可复用报价单
• 付款：自动识别 BOLT11 发票、BOLT12 报价单、闪电地址（如 user@getalby.com）和 LNURL
• 交易历史：本地持久化存储所有收付款记录
• 守护进程管理：自动或手动启动/停止/重启本地 HTTP 服务

技术架构：

• 本地守护进程绑定 3456 端口，仅监听 localhost（外部不可访问）
• 通过出站连接接入 MDK 闪电网络基础设施
• 每 30 秒轮询一次入款状态
• 数据持久化至 ~/.mdk-wallet/ 目录（含配置、助记词、交易历史）

显著优点

1. 极致简化：零配置设计，一个命令完成初始化，所有输出均为 JSON 格式便于程序解析
2. 完全自托管：私钥（BIP39 助记词）仅存储于本地，用户拥有完整资金控制权
3. 多协议支持：原生兼容 BOLT11、BOLT12、LNURL、闪电地址等主流闪电网络标准
4. Agent 原生：专为 AI 代理场景设计，支持代理间直接支付
5. 透明可审计：完全开源（GitHub 可查），可验证无外部数据泄露

潜在缺点与局限性

1. 安全风险集中：助记词以明文存储于 ~/.mdk-wallet/config.json，依赖文件系统权限保护；若设备被入侵，资金可能被盗
2. 单点故障：本地守护进程崩溃或端口冲突会导致服务中断
3. 无多签/社交恢复：纯单密钥方案，助记词丢失即永久失去资金访问权
4. 网络依赖：依赖 MDK 基础设施的出站连接，若 MDK 服务异常可能影响功能
5. 人机交互悖论：设计为"Agent 自主"但实际要求关键操作（如暴露助记词、删除钱包）必须人工确认，自动化场景存在摩擦

适合人群

• 需要为 AI 代理集成比特币支付能力的开发者
• 追求自托管、不愿依赖托管式钱包的隐私敏感用户
• 实验性 Agent 经济/代理间支付场景的探索者
• 熟悉命令行操作、能理解私钥管理责任的技术用户

常规风险

| 风险类别 | 具体描述 | 缓解建议 |

|---------|---------|---------|

| **私钥泄露** | `init --show` 命令输出明文助记词，提示注入攻击可导致私钥被窃取 | 严禁在 Agent 上下文中执行此命令；仅在安全终端由人工操作；禁止日志记录助记词 |

| **资金丢失** | 助记词未备份或文件被误删（`rm -rf ~/.mdk-wallet`） | 首次初始化后立即人工备份助记词；使用 `trash` 替代 `rm`；删除前强制人工确认 |

| **未授权支付** | Agent 被诱导向恶意地址付款 | 默认要求显式用户批准；预授权自动支付需设置明确白名单/限额 |

| **版本风险** | npx 默认使用最新版，可能引入未预期变更 | 生产环境锁定版本（如 `@0.11.0`） |

| **本地服务暴露** | 守护进程配置错误导致端口对外暴露 | 确认仅绑定 `localhost:3456`；检查防火墙规则 |

核心用法

agent-wallet是一款专为AI代理设计的自托管比特币闪电网络钱包，由Anthropic的MoneyDevKit团队开发。该技能通过npm包@moneydevkit/agent-wallet提供，采用纯命令行交互模式，所有操作返回JSON格式输出，便于程序化处理。

初始化过程极简：执行npx @moneydevkit/agent-wallet init即可自动生成BIP39助记词、创建配置文件并启动本地守护进程。钱包支持完整的闪电网络操作：查询余额（balance）、生成收款发票（receive/receive-bolt12）、付款（send）、查看交易历史（payments）等。协议兼容性出色，支持Bolt11发票、Bolt12可复用报价单、LNURL和闪电地址（如user@getalby.com）等多种收款方式。

技术架构上，该钱包采用本地守护进程模式：在localhost:3456运行HTTP服务，自动连接MDK闪电网络基础设施，每30秒轮询入账付款，无需配置Webhook端点。钱包数据持久化存储于~/.mdk-wallet/目录，包括配置、助记词和交易历史。

显著优点

极致简洁的部署体验：真正实现"零配置"——无需API密钥、无需注册账户、无需搭建完整节点，单个命令即可完成钱包初始化。这对于希望快速赋予AI代理支付能力的开发者极具吸引力。

完整的协议支持：兼容闪电网络主流标准，既支持传统的一次性Bolt11发票，也支持可复用的Bolt12报价单；付款端自动识别发票、报价单、LNURL和闪电地址，降低集成复杂度。

自托管与隐私性：用户完全掌控私钥（BIP39助记词），无托管方风险。本地守护进程设计确保敏感操作在本地完成，仅必要的闪电网络协议数据对外传输。

AI原生设计：JSON输出格式、退出状态码规范、明确的Agent安全规则（如禁止自动执行init --show），体现了对AI自动化场景的深入考量。

潜在缺点与局限性

安全风险集中化：助记词以明文形式存储于~/.mdk-wallet/config.json，依赖文件系统权限保护。一旦该文件泄露，资金将完全失控。文档虽明确警告，但"便利性优先于安全性"的设计哲学对高价值场景可能不够审慎。

网络依赖与单点故障：必须持续连接MDK基础设施，若服务中断则钱包功能受限。守护进程轮询模式（30秒间隔）对实时性要求高的场景存在延迟。

比特币闪电网络的固有限制：需预先充值才能付款；通道流动性管理复杂；小额支付场景外的大额交易可能面临路由失败。此外，闪电网络仍处于发展期，协议变更可能影响兼容性。

无多签与恢复机制：仅支持单助记词控制，无私钥分片、多签或社交恢复等进阶安全功能。助记词丢失即资金永久损失，对自动化Agent的容错能力要求较高。

适合的目标群体

• AI Agent开发者：需要为智能体赋予自主支付能力，构建"Agent经济"的原型或产品
• 自动化脚本工程师：希望通过闪电网络实现程序化、小额、高频的比特币收付
• 加密货币实验者：探索AI与加密货币结合的创新应用场景
• 小额服务提供商：接受闪电网络付款的内容创作者、API服务、微任务平台

不适合：大额资金托管、机构级合规要求、对安全容错有极高要求的场景。

使用风险

私钥泄露风险：助记词文件权限配置不当、备份存储不安全、或Agent被诱导执行init --show均可能导致资金被盗。建议严格限制~/.mdk-wallet/目录权限（600），助记词备份采用离线加密存储。

供应链攻击：npm包或MDK基础设施若被篡改，可能危及资金安全。生产环境务必锁定版本（如@0.11.0），监控依赖更新。

意外资金损失：Agent误操作付款、金额单位错误（sats vs BTC）、或发送至错误地址均不可逆。建议实施付款确认机制，除非用户明确授权，否则禁止自主付款。

守护进程可用性：Daemon崩溃或端口冲突（3456被占用）将导致钱包功能中断。需监控进程状态，配置自动重启机制。

闪电网络流动性风险：入账资金需通道容量支持，付款失败可能源于路由问题而非余额不足。