1. 项目概述一个为AI智能体设计的双协议支付网关如果你正在构建一个能够自主行动的AI智能体比如一个能帮你订餐、购物甚至管理投资的数字助手那么一个核心问题就会浮现它怎么付钱传统的支付接口都是为人设计的需要登录、验证、输入密码这些步骤对AI来说几乎不可能完成。而agentic-payments-bot这个项目就是为了解决这个“最后一公里”问题而生的。简单来说这是一个专门为AI智能体Agent打造的支付服务。它不是一个简单的支付SDK而是一个完整的、支持双协议x402和AP2的支付网关。你可以把它想象成AI世界的“支付宝”或“Stripe”但它服务的对象不是人类用户而是像OpenClaw、Claude Code、GitHub Copilot这样的AI程序。这个项目最核心的价值在于它让AI具备了安全、合规、可审计的“花钱”能力。无论是支付一笔云服务器费用还是购买一个API调用额度AI都可以在预设的规则内自主完成无需人类每一步都点头确认。我花了相当长的时间研究AI与支付的结合发现痛点非常明确要么支付流程太“重”AI无法介入要么安全性太“裸”让AI直接操作私钥或信用卡无异于敞开大门。agentic-payments-bot的设计思路很聪明它没有重新发明轮子而是充当了一个“翻译官”和“守门人”的角色。它把AI发出的支付意图比如“用5美元的USDC支付给这个API服务”翻译成区块链Web3或传统金融Web2世界能理解的语言并且在执行前会经过一套严格的策略引擎Policy Engine审查确保这笔交易符合你事先设定的所有规则。2. 核心架构与设计哲学2.1 双协议支持x402与AP2的互补之道这个项目的基石是它对两个新兴支付协议的原生支持x402和AP2。理解这两者的区别和适用场景是用好这个工具的关键。x402协议由Coinbase推动其核心思想非常极客复活HTTP协议中那个几乎被遗忘的402 Payment Required状态码。想象一下你的AI访问一个需要付费的API服务器不是返回错误而是优雅地回复“402请付钱”并在响应头里告诉你该付多少、付给谁、用什么币。你的AI支付网关看到这个就能自动构造一笔链上交易完成支付然后重新请求获得数据。这个过程是无状态和HTTP原生的特别适合为按次付费的API、数字内容设置“付费墙”。它的支付是即时且不可逆的就像你在便利店扫码买瓶水。AP2协议由Google提出思路则更偏向于“授权”与“凭证”。它引入了“授权书”Mandate的概念。你可以先签署一份授权书规定“我的AI助手可以在未来24小时内在亚马逊上购买总额不超过100美元的商品”。AI在购物时会基于这份授权书生成更具体的“购物车授权书”和“支付授权书”并最终获取一个有时效性、有额度限制的支付令牌来完成交易。这个过程更像是一张有严格条款的信用卡副卡适合电商购物、订阅服务等需要一定灵活性和退款可能的场景。agentic-payments-bot同时扮演了这两个协议的客户端和服务器端。作为客户端它能让你的AI去支付其他支持x402或AP2的服务。作为服务器端它能让你的服务轻松地向其他AI收费。这种双向能力构成了一个支付生态的闭环。2.2 系统架构全景模块化与安全性至上整个系统的架构清晰体现了模块化设计的思想各个组件职责分明通过清晰的接口进行通信。从上到下我们可以将其分为四层接口层提供了三种交互方式。Web APIRESTful供其他程序调用命令行界面CLI方便运维和调试OpenClaw Skill集成则让其能无缝接入OpenClaw等AI智能体平台通过自然语言触发支付。协议路由与解析层这是系统的“大脑”。它接收来自各接口的请求核心任务之一是解析AI的输出。AI可能会在对话中说“请向0xabc...地址支付0.1个ETH作为服务器费用”路由层需要从中精准提取出支付金额、收款方、货币类型等关键信息并将其标准化为一个内部的PaymentIntent支付意图对象。然后根据PaymentIntent中的信息如指定的网关、收款地址格式将其路由到正确的支付处理模块。策略与安全层这是系统的“守门人”。在支付执行前Policy Engine会介入根据配置文件中的规则进行多重检查。同时所有敏感的私钥或API密钥都不以明文存储而是通过一个可插拔的KMS密钥管理服务提供商系统进行加密后存入数据库。系统支持从AWS KMS这样的云服务到操作系统自带的钥匙串Keychain/Keyring再到本地的GnuPG加密等多种后端确保密钥安全。支付执行与数据层这是系统的“手脚”。包含具体的支付实现web3模块通过Viem库处理以太坊、Base等区块链上的ETH及ERC-20代币转账web2模块集成Stripe、PayPal、Visa Direct等传统支付网关。所有操作记录都会被写入SQLite数据库形成完整的审计追踪链包括交易详情、策略检查结果、人工确认记录等。数据流向也分为清晰的“客户端”和“服务器端”两条路径。客户端路径是“AI主动付钱出去”经历解析、路由、策略检查、密钥解密、支付执行、记录审计的完整流程。服务器端路径是“外部AI付钱进来”通过x402的402响应流程或AP2的授权书处理流程验证支付有效性后再调用内部的支付执行模块完成收款并记录日志。3. 核心组件深度解析与实操要点3.1 密钥管理安全基石的设计与选型私钥和API密钥的安全是支付系统的生命线。agentic-payments-bot设计了一套灵活且强大的KMS提供商系统这是我认为项目中最值得称道的安全设计之一。核心机制系统定义了一个统一的KmsProvider接口所有具体的密钥管理实现都必须遵守这个接口。当需要存储一个密钥时系统会调用当前激活的Provider的encryptAndStore方法该方法返回一个CiphertextBlob密文块和相关的元数据然后将其存入SQLite的encrypted_keys表。读取时则用对应的retrieveAndDecrypt方法解密。密钥本身永远不会以明文形式出现在应用内存之外。提供商选型指南 不同的提供商适用于不同的部署环境选择合适的是平衡安全性与便利性的关键。提供商最佳适用场景安全等级便利性关键注意事项AWS KMS生产环境云部署极高高需配置IAM权限产生API调用费用。密钥由AWS完全托管无法导出。OS Keyring个人开发机桌面环境高极高利用系统原生钥匙串macOS Keychain, Windows Credential Manager, GNOME Keyring等。密钥被操作系统级保护。D-Bus Secret ServiceLinux桌面环境高高依赖dbus和secret-tool适合GNOME或KDE桌面。GnuPG无图形界面的Linux服务器中高中需要预先配置GPG密钥对。适合headless无头服务器环境。Local AES测试、Dry-Run模式低极高使用一个本地配置文件中的密钥进行加密。切勿用于生产环境仅用于功能验证。实操心得在开发测试阶段我强烈建议使用Local AES提供商并开启DRY_RUN模式这样可以快速跑通流程无需配置任何外部密钥服务。当准备部署到生产环境时再根据你的基础设施选择。如果是AWS生态直接用AWS KMS最省心如果是自己的物理服务器GnuPG是个可靠的选择。切换提供商只需在配置文件中修改kms.provider字段系统会自动用新Provider重新加密所有已存储的密钥这个过程是平滑的。无头环境下的回退逻辑这是项目考虑周到的一个细节。当在无图形界面的服务器上运行时如果配置了OS Keyring系统会检测到环境不支持并自动按预设的优先级列表可在配置中定义回退到下一个可用的Provider比如GnuPG。这确保了部署的鲁棒性。3.2 策略引擎为AI支付套上缰绳让AI自主支付最大的担忧就是失控。策略引擎就是控制这匹“骏马”的缰绳。它不是一个简单的“是/否”检查器而是一个可配置的、带状态追踪的规则评估系统。规则类型详解 策略规则在YAML配置文件中定义支持多种维度组合单次交易限制maxAmountPerTransaction。这是最基本的防线防止单笔支付过大。时间聚合限制maxAmountPerDay/Week/Month。系统会在数据库transactions表中维护按时间窗口聚合的支付总额实时检查。这是控制月度预算的关键。时间段限制allowedTimeWindows。可以设定只允许在工作日的工作时间进行支付防止AI在深夜或周末进行异常操作。黑白名单recipientBlacklist和recipientWhitelist。你可以直接封禁某些地址或设置“只允许支付给以下地址”的白名单极大提升安全性。货币限制allowedCurrencies。可以限制只允许使用USDC稳定币支付避免加密货币价格波动带来的风险。人工确认反馈环 策略引擎的精髓在于“升级”机制。当一笔支付请求触发任何一条规则比如金额超过单笔限额或在非工作时间发起它不会直接拒绝而是会启动“人工确认”流程。根据配置这个确认请求可以通过CLI命令行提示、Web API的回调端点或者集成到OpenClaw的聊天界面中等待人类管理员审批。只有得到确认后支付才会继续执行。踩坑记录在早期测试中我曾忘记设置allowedTimeWindows结果模拟的AI在凌晨3点尝试支付直接通过了。虽然只是测试但让我惊出一身冷汗。因此我的建议是在任何正式部署中至少启用“单次限额”和“日聚合限额”并为“时间段限制”设置一个合理的范围例如工作日9-18点。同时务必配置好人工确认的渠道比如一个监控用的Telegram Bot确保异常支付能被及时拦截和审查。3.3 双协议客户端的实现与调用作为支付网关的核心功能如何驱动它去支付外部服务这主要通过两个协议客户端模块实现。x402客户端支付流程 假设你的AI需要访问一个收费的天气API该API使用了x402协议。发现阶段你的AI通过本支付网关首次请求https://api.premium-weather.com/v1/forecast。收到402服务器返回402 Payment Required状态码并在X-Payment头中携带一个Base64编码的JSON内容类似{scheme:erc20,network:base,amount:5.00,asset:USDC,payTo:0xMerchantAddress...,maxTimeoutSeconds:300}。构造并签名支付支付网关解析该信息从KMS解密出对应的私钥使用Viem库构造一个符合EIP-3009标准的transferWithAuthorization签名。这个签名包含了金额、接收方、有效期等信息。重试请求将签名后的支付授权再次Base64编码放入新的X-Payment请求头中重新发起GET请求。获得资源资源服务器的“协调者”会验证签名并在链上结算。成功后返回200 OK和所需的天气预报数据同时在X-Payment-Response头中返回链上交易哈希作为收据。AP2客户端支付流程 假设你的AI需要在支持AP2的电商网站购买一本书。创建授权书网关根据AI的意图“购买一本售价20美元的书”生成一个IntentMandate包含最大金额、有效期、商户ID等约束。获取用户签名这个IntentMandate需要发送到配置的“凭证提供者”可能是一个需要用户手动确认的App或在本项目中模拟进行数字签名证明用户知情并同意。锁定购物车AI找到具体的商品后生成一个CartMandate锁定商品ID和精确价格20美元。获取支付凭证将签名的IntentMandate和CartMandate提交给支付网关的AP2服务器端点申请一个针对此次交易的、令牌化的支付凭证。提交支付最后将授权书和支付凭证一起提交给电商的AP2支付端点完成扣款。在代码中你通常不需要直接调用这些底层客户端。更常见的做法是让你的AI例如OpenClaw直接输出结构化的支付意图或者通过Web API提交一个PaymentIntentJSON对象。协议路由器会自动识别并处理。4. 从零开始的完整部署与实操指南4.1 环境准备与快速启动最快上手的方式就是使用项目提供的Docker Compose配置。这能帮你避开复杂的依赖安装和环境配置。第一步获取代码与配置git clone https://github.com/sentient-agi/agentic-payments-bot.git cd agentic-payments-bot cp .env.example .env # 复制环境变量模板此时先不要编辑.env文件。我们首先在“干跑”模式下测试所有功能。第二步以Dry-Run模式启动Dry-Run模式是项目的亮点它使用桩函数模拟所有支付网关和KMS操作让你在不涉及真实金钱和密钥的情况下完整跑通全流程。DRY_RUNtrue docker compose up --build -d这条命令会构建镜像并启动两个核心服务支付网关的REST API端口3402和OpenClaw网关服务。启动后可以检查健康状态curl http://localhost:3402/api/v1/health如果返回{status:ok}说明服务已就绪。第三步运行演示脚本项目内置了一个演示脚本可以一次性展示多种支付场景。DRY_RUNtrue docker compose run --rm cli demo你会看到终端输出一系列步骤模拟了从解析AI对话、创建支付意图、策略检查、到模拟执行Web3转账、Stripe支付等全过程。这是理解系统工作流最直观的方式。第四步探索CLI工具CLI是与支付网关交互的利器。在Dry-Run模式下你可以安全地尝试所有命令。# 列出当前存储的密钥Dry-Run下会有一个模拟密钥 DRY_RUNtrue docker compose run --rm cli keys list # 模拟解析一段AI文本并执行支付 DRY_RUNtrue docker compose run --rm cli parse --text 请向0x742d35Cc6634C0532925a3b844Bc9e90F1A90401转账0.01 ETH作为网络费用。 # 查询审计日志查看所有操作记录 DRY_RUNtrue docker compose run --rm cli audit --limit 104.2 生产环境配置与密钥管理当你通过Dry-Run模式熟悉了系统准备投入真实使用时就需要进行生产配置。核心在于.env文件和config/default.yaml文件。1. 配置环境变量 编辑.env文件填入你的真实凭证。以下是最关键的几项# 示例使用AWS KMS管理密钥 KMS_PROVIDERaws-kms AWS_REGIONus-east-1 AWS_KMS_KEY_IDarn:aws:kms:us-east-1:123456789012:key/your-key-id # AWS访问密钥需要通过IAM角色或环境变量提供 # 示例使用Stripe支付 STRIPE_SECRET_KEYsk_live_... STRIPE_WEBHOOK_SECRETwhsec_... # 连接OpenClaw如果需要 OPENCLAW_GATEWAY_TOKENyour_gateway_token_here LLM_PROVIDERanthropic # 或 openai, groq等 LLM_API_KEYsk-your-llm-api-key重要安全提示永远不要将.env文件提交到版本控制系统。确保它在.gitignore列表中。在生产服务器上可以考虑使用Docker Secrets或云服务商提供的密钥管理服务来注入这些变量。2. 配置策略规则 编辑config/default.yaml中的policy部分。这里是一个相对严格的生产环境起点配置policy: rules: - name: global-limits maxAmountPerTransaction: 1000.00 # 单笔不超过1000美元等值 maxAmountPerDay: 5000.00 maxAmountPerWeek: 20000.00 maxAmountPerMonth: 50000.00 allowedTimeWindows: - days: [1,2,3,4,5] # 周一至周五 start: 09:00 end: 18:00 allowedCurrencies: [USDC, USDT] # 只允许使用稳定币 recipientBlacklist: [] # 显式黑名单 # recipientWhitelist: [0x123...] # 如果启用白名单则只允许向此列表中的地址支付 humanConfirmation: requiredForViolations: true method: cli # 或 webhook, chat。生产环境建议用webhook对接你的监控系统。3. 初始化真实密钥 在Dry-Run模式下我们用的是模拟密钥。现在需要添加真实的区块链钱包私钥或支付API密钥。# 假设你已配置好AWS KMS和.env先关闭Dry-Run模式 docker compose down # 以生产模式启动服务 docker compose up -d # 通过CLI添加一个以太坊私钥系统会提示你输入输入后会被加密存储 docker compose run --rm cli keys add --name main-wallet --type evm-private-key # 按提示粘贴你的私钥0x开头64字符 # 添加Stripe密钥 docker compose run --rm cli keys add --name stripe-prod --type stripe-secret-key # 按提示粘贴你的 sk_live_... 密钥添加后你可以用keys list命令查看密钥列表只显示元数据不显示明文确保密钥已安全存储。4.3 与OpenClaw智能体集成实战agentic-payments-bot的一个强大之处是作为OpenClaw的一个“技能”运行。这意味着你的OpenClaw智能体天生就具备了支付能力。集成原理Docker Compose启动时会自动将项目的SKILL.md文件一个符合Open Agent Skills Ecosystem规范的技能描述文件符号链接到OpenClaw的技能目录。OpenClaw启动时会加载这个技能从而在它的“工具箱”里注册一个支付功能。在聊天中触发支付 当你在与OpenClaw对话时你可以直接说“请从我的主钱包支付5美元的USDC到地址 0xRecipientAddress用于支付API费用。”OpenClaw会调用支付技能。支付技能会解析你的自然语言提取出amount: 5,currency: USDC,recipient: 0x...,gateway: web3等信息形成PaymentIntent。执行策略检查。如果需要人工确认会在聊天界面中向你弹出确认请求例如“检测到一笔向新地址的支付是否继续”。获得确认后从KMS解密私钥通过Viem发起区块链交易。将交易哈希结果返回聊天界面。自定义技能触发词你可以修改SKILL.md文件中的triggers部分添加更多你习惯的自然语言表达方式比如“转账”、“打款”、“支付费用”等让AI更准确地识别你的支付意图。5. 常见问题排查与运维技巧在实际部署和运行中你可能会遇到一些问题。以下是我在测试和使用中总结的一些常见情况及解决方法。5.1 支付失败排查清单当一笔支付执行失败时不要慌张按照以下步骤进行排查现象可能原因排查步骤CLI/API返回“策略拒绝”支付请求违反了策略规则。1. 运行cli audit --limit 5查看最新审计日志找到被拒的交易ID。2. 查看日志中policy_decision和violated_rules字段明确违反哪条规则。3. 检查config/default.yaml中的对应规则配置。区块链交易失败如Reverted链上执行失败可能原因余额不足、Gas过低、合约交互错误。1. 使用cli tx get --id tx_id获取交易详情找到链上交易哈希。2. 用区块链浏览器如Etherscan查询该哈希查看具体的失败原因。3. 检查发送账户的ETH余额用于支付Gas和代币余额是否充足。4. 在配置中适当调高payments.web3.gasLimitMultiplier。Web2支付网关返回错误如Stripe拒绝卡片拒绝、风控、API密钥无效或权限不足。1. 查看应用日志docker compose logs agentic-payments-bot寻找来自Stripe/PayPal等的错误响应。2. 登录对应的支付网关商户后台查看拒付详情和风控提示。3. 确认使用的API密钥具有正确的权限如charges:write。4. 检查收款人信息如邮箱、国家是否符合网关要求。x402支付始终收到402响应支付签名无效、网络或资产不支持、支付超时。1. 确认配置中支持目标网络如Base和资产如USDC。2. 检查用于签名的私钥对应的地址是否有足够余额。3. 审计日志会记录发送的X-Payment头可解码后检查签名内容是否与402响应中的要求一致。4. 确保系统时间准确防止签名中的时间戳过期。AP2流程卡在“等待凭证”凭证提供者未响应、授权书签名无效。1. 确认AP2服务器端点/api/v1/ap2/sign-mandate配置正确且可访问。2. 检查授权书的expiresAt字段是否已过期。3. 验证用于签名授权书的私钥是否与凭证提供者注册的公钥匹配。5.2 性能优化与监控建议对于生产环境除了功能还需关注稳定性和可观测性。数据库优化SQLite在轻量级应用上表现很好但支付日志表audit_log可能增长很快。建议在docker-compose.yml中为数据库文件挂载的卷使用tmpfs内存盘以获得极致IO速度但要注意数据持久化问题。更稳妥的做法是挂载到高性能的SSD磁盘。定期归档旧日志。可以写一个定时任务Cron Job每月将超过3个月的audit_log记录转移到另一个归档表或文件中保持主表精简。日志聚合项目使用Winston日志库同时输出到控制台和文件。在生产中你应该配置一个日志传输将日志发送到如Loki、Elasticsearch或云服务商的日志服务中方便集中查询和设置告警。可以修改src/logging/logger.ts文件添加相应的Winston Transport。健康检查与告警Web API提供了/api/v1/health端点。你可以在Kubernetes或Docker Swarm中将其配置为存活探针和就绪探针。此外可以监控/api/v1/audit端点对“policy_violation”或“payment_failed”类型的事件设置告警及时通知管理员。5.3 扩展与自定义开发项目采用了清晰的模块化设计使得扩展新的支付网关或修改现有逻辑变得相对容易。添加一个新的Web2支付网关在src/payments/web2/gateways.ts中参照StripeGateway类创建一个新的类实现PaymentGateway接口。在该类的executePayment方法中实现调用该网关API的具体逻辑。在gateways映射对象中注册你的新网关例如my-new-gateway: new MyNewGateway()。在config/default.yaml的payments.web2部分添加对应的配置块。现在当PaymentIntent中指定gateway: my-new-gateway时协议路由器就会调用你的实现。修改策略规则逻辑 策略引擎的规则定义在配置文件中但评估逻辑在src/policy/engine.ts。如果你想实现更复杂的规则例如“禁止在节假日支付”或“根据收款地址信誉评分动态调整限额”可以修改evaluatePolicy函数添加自定义的规则检查逻辑。我个人的使用体会是这个项目最吸引人的地方在于它提供了一个安全、可审计的框架而不是一个封闭的黑盒。它承认AI自主支付的复杂性并通过协议抽象、策略引擎和密钥管理这三个支柱将风险控制在可管理的范围内。它不是让你盲目信任AI而是让你能够清晰地定义信任的边界并在边界被触碰时得到通知。从Dry-Run模式开始的渐进式上手路径也非常友好让你可以在不承担任何风险的情况下彻底理解整个系统是如何运作的这在涉及真金白银的金融科技项目中至关重要。