ixrail AgentPay是什么：在VS Code里给AI Agent装上钱包与预算的完整指南-育师

【免费下载链接】ixrail

Chaos

项目地址：https://gitcode.com/gh_mirrors/by/ixrail

ixrail AgentPay是一款 VS Code 扩展，它为本地 AI Agent 提供钱包与预算管理：通过 x402 支付协议与 USDC 稳定币结算，让 AI Agent 在调用 API、获取数据或消耗算力时自主完成付款，且每笔交易都有签名回执可审计。本文将从安装、零成本沙盒演示到支出策略配置，带你一步步给 AI Agent 装上一副"有预算约束的钱包"。

什么是 ixrail AgentPay？

一句话概括：它是一个Agent 钱包 + 支出策略 + 认证本地经纪人 + x402 支付流 + 签名回执账本的组合体，全程不离开编辑器。

能力	说明
🔐 Agent 钱包	通过 VS Code`SecretStorage`创建并保管 EOA 钱包（测试网 Base Sepolia / 主网 Base）
📊 支出策略	单笔、每日、每月三级限额 + 人工审批阈值 + 商户允许/阻止名单
🌐 本地经纪人	仅监听回环地址的认证 HTTP 端点，让本地 Agent 以 Bearer Token 调用 AgentPay 工具
🧾 签名回执	每笔已结算支付都产出一条防重放、可独立验证的签名回执
🔌 MCP 服务器	无第三方依赖的 stdio MCP 服务器，任何 MCP 兼容客户端都能直接调用同一组工具
🧪 沙盒演示	内置模拟商户 + 模拟结算，零资金跑通"支付 → 回执"完整闭环

为什么 AI Agent 需要钱包与预算

随着 Agent 框架和 MCP 服务器能力增强，它们越来越多地为消耗的资源付费——API 调用、数据、算力——而每一笔交易都不现实地由人肉在场审批。但直接把钱交给 Agent 又让人不放心。ixrail AgentPay 的思路是：给 Agent 钱包，但把花钱的缰绳留在人手里：

每次结算前都先过策略校验，超额或被阻止名单命中的请求直接拒绝；
金额达到审批阈值时，必须在 VS Code 中显式确认才会继续结算；
已批准的支出会被"预留"10 分钟，防止并发请求同时冲破限额；
发现 Agent 行为异常时，一键Revoke access立即停止其所有付款，并清空在途预留。

快速安装：VS Code 中一条命令搞定

最快的开始方式是从 VS Code Marketplace 安装ixrail AgentPay（扩展 ID 为ixrail.ixrail）：

code --install-extension ixrail.ixrail

也可以按Ctrl+Shift+X（macOS 为Cmd+Shift+X）打开扩展视图，直接搜索ixrail AgentPay安装。

环境要求（详见 package.json）：

VS Code ≥ 1.85
Node.js ≥ 18（仅本地开发或运行独立进程时需要）

如果你想从源码构建，克隆仓库后依次执行npm install→npm run build，再按F5打开扩展开发宿主即可调试；四个入口的打包布局可查看 esbuild.js。

三步沙盒演示：不花一分钱体验完整支付流

ixrail AgentPay 自带引导式沙盒演示：自动创建名为sandbox-demo的 Base Sepolia 钱包、应用仅限 localhost 的策略、启动认证经纪人和内置模拟商户，全程不需要真钱。

Set Up Sandbox Demo：一键创建钱包、应用策略、启动经纪人，并复制经纪人 Bearer Token；
Pay endpoint：选择sandbox-demo代理，输入模拟商户地址http://127.0.0.1:4021/v1/weather——该商户固定收费 0.05 USDC，并会拒绝任何回执证明的二次重放；
查看回执：在 Agent 卡片中查看近期付款，或打开All receipts查看签名回执账本，还能对回执做签名验证。

默认情况下ixrail.simulateSettlement为开启状态，扩展会完整执行"策略校验 → 付款签名 → 402 重试 → 签名回执"流程，但不会真正广播链上交易。想测试真实的 Base Sepolia USDC 转账时，关闭该设置，为钱包注入 Base Sepolia USDC 和少量 ETH 作 gas 后再次支付即可。

设置支出策略：给 AI Agent 的四层预算控制

在侧边栏选中某个 Agent，选择Set policy后，所有 x402 结算尝试在签名前都会经过以下检查：

控制项	作用
单笔上限（Per-transaction cap）	一次支付的最大金额
每日上限（Daily cap）	当前 UTC 日已记录支出 + 在途预留之和
每月上限（Monthly cap）	当前 UTC 月已记录支出 + 在途预留之和
审批阈值（Approval threshold）	达到或超过该金额，需要人工在 VS Code 中显式确认
允许 / 阻止名单	商户域名或收款地址白名单；允许名单为空表示"放行所有未被阻止的对象"，阻止名单始终优先

两个值得注意的细节：

预留机制：已批准的支出会预留 10 分钟，避免并发请求竞争冲破上限；交易失败时预留自动释放；
吊销与恢复：吊销会拒绝该 Agent 的全部支付并清空调预留；重新创建或更新策略时，会自动恢复此前被吊销的 Agent。

x402 支付流程：Agent 如何为 API 自动买单

x402 是一种用 HTTP 402 状态码表达"需要付款"的支付协议。pay_x402_endpoint工具的工作方式如下：

Agent 先正常请求目标资源；若响应不是 402，直接返回结果，不发生支付；
收到 402 后，AgentPay 读取付款要求并逐项校验：金额为正数、资产为USDC、收款地址是合法 EVM 地址、链为base-sepolia或base、钱包链一致；
再叠加校验调用方传入的最大金额与 Agent 策略，通过后预留支出并签名付款；
结算完成后，AgentPay 签署一份规范化回执，携带X-Payment-Proof与X-Ixrail-Receipt请求头重试原始请求；
最后把支出记入日/月限额，并释放预留。

完整的组件地图与数据流可以参考 docs/ARCHITECTURE.md。

MCP 服务器与本地 Broker：让其他 Agent 也能调用

除 VS Code 界面外，同样的 6 个工具（get_balance、request_payment、pay_x402_endpoint、create_spending_policy、get_receipt、revoke_agent_access）可以通过两条通道对外暴露：

stdio MCP 服务器：基于 stdio 的无依赖 JSON-RPC 运行时，支持 initialize、工具发现、ping 与工具调用，可直接接入任何 MCP 兼容客户端。在扩展中使用Copy MCP Configuration可自动生成客户端配置，并通过IXRAIL_AGENTPAY_STORE指定独立存储文件；
HTTP 经纪人：默认监听127.0.0.1:4022，只接受回环地址绑定，每个/tools/*请求都必须携带Authorization: Bearer <token>头（采用时序安全的比较方式），GET /health则保持开放以便探活。

相关安全设计与细节见 SECURITY.md。

真实 USDC 结算前必须知道的注意事项

沙盒模式不移动任何代币。启用真实链上 USDC 结算前，请先了解这些限制：

链上模式钱包需同时持有 USDC 与 ETH（作 gas）；金额以数字表示并四舍五入到 6 位小数，适合受控的开发工作流，而非高金额资金操作；
get_balance目前报告的是原生 ETH 余额，不是USDC 代币余额；
Base 主网转账默认禁用，需显式设置IXRAIL_ALLOW_MAINNET_PAYMENTS=1才能开启——转账不可逆，连接陌生端点前请收紧允许名单并调低限额；
本版本提交交易后不会等待确认，请在认定支付"最终完成"前独立核验该交易；
x402 服务端控制它返回的付款要求，因此对不熟悉的端点务必配合严格允许名单和低限额使用。

常见问题速查

现象	快速排查
`/tools/*`返回 401 Unauthorized	确认`Authorization: Bearer <token>`完全一致；重启且未设置`IXRAIL_HTTP_TOKEN`会生成新 token
经纪人拒绝启动	只支持`127.0.0.1`、`::1`、`localhost`三种回环主机
支付被策略拒绝	依次检查：是否被吊销、允许/阻止名单、单笔上限、UTC 日/月累计支出、在途预留、`maxAmountUsd`
支付要求人工审批	金额达到审批阈值；独立 HTTP/stdio 进程没有审批 UI，默认拒绝"需审批"的结算，如需无人值守请刻意调整策略
端口 4021 / 4022 被占用	用`IXRAIL_MOCK_MERCHANT_PORT`改商户端口，用`IXRAIL_HTTP_PORT`或`ixrail.brokerPort`改经纪人端口

项目文件导航

文件	说明
README.md	完整文档：安装、沙盒演示、策略、x402 行为与环境变量
docs/ARCHITECTURE.md	组件地图、数据流与信任边界
package.json	扩展清单、贡献的命令与设置项、构建脚本
esbuild.js	扩展、MCP 服务器、HTTP 桥、模拟商户四个入口的打包配置
CHANGELOG.md	版本历史（当前版本 0.2.6）
SECURITY.md	安全机制与漏洞报告渠道

写在最后

ixrail AgentPay 本质上是一个装在 VS Code 里的"AI Agent 收银台"：Agent 拥有自己的钱包，花钱受策略约束，结算留签名回执，人始终握有一票否决权。建议先跑一遍零成本的沙盒演示，再逐步过渡到真实的 USDC 结算——先让 Agent 在预算之内学会花钱，再去扩大它的钱包权限。