如何快速上手ixrail AgentPay:10分钟安装配置AI Agent支付工具完整教程
如何快速上手ixrail AgentPay:10分钟安装配置AI Agent支付工具完整教程
ixrail AgentPay 是一款面向 AI Agent 的支付工具,它以 VS Code 扩展的形式,给你的 AI Agent 配备一个加密钱包、一套可配置的预算策略、一条受治理的 x402 支付通道和一份可验证的签名收据台账——全程无需离开编辑器,且支持零资金的沙盒模拟结算,非常适合新手快速体验 AI Agent 自主支付的完整流程。
一、什么是 ixrail AgentPay?AI Agent 支付工具能做什么 🤖
当 AI Agent、MCP 服务器或 Agent 框架需要为调用的 API、数据、算力等资源付费时,ixrail AgentPay 让这一切在编辑器内完成:
- 🔐 钱包管理:Agent 钱包通过 VS Code
SecretStorage创建和安全存储 - 📊 支出策略:单笔/每日/每月限额、人工审批阈值、商户白名单与黑名单
- 🌐 本地 Broker:认证过的 localhost 服务,让本地 Agent 通过 HTTP 调用支付工具
- 🧾 签名收据:每笔已结算支付都会生成防重放的可验证收据
- 🔌 MCP 服务器:无依赖的 stdio MCP 服务,可接入任意 MCP 兼容客户端
- 🧪 沙盒演示:内置模拟商户与引导式流程,零资金跑通完整的“支付 → 收据”闭环
组件全貌可参考 docs/ARCHITECTURE.md,其中包含各组件入口、x402 支付数据流和信任边界说明。
二、环境准备与一键安装:3 种安装方式任选 ⚡
环境要求
| 组件 | 版本要求 |
|---|---|
| VS Code | 1.85 或更新 |
| Node.js | 18 或更新(仅源码构建需要) |
| npm | 随 Node.js 安装 |
方式一:命令行一键安装(最快)
打开 VS Code 终端,执行:
code --install-extension ixrail.ixrail
方式二:扩展市场图形化安装
按 Ctrl+Shift+X(macOS 为 Cmd+Shift+X)打开扩展视图,搜索 ixrail AgentPay,点击安装即可。
方式三:从源码克隆仓库并构建 🛠️
适合希望调试或二次开发的用户:
git clone https://gitcode.com/gh_mirrors/by/ixrail
cd ixrail
npm install
npm run build
构建由 esbuild.js 驱动,会打包 4 个产物:扩展宿主 out/extension.js、MCP 服务器 out/mcp/server.js、HTTP 桥接 out/mcp/httpBridge.js 和模拟商户 out/mock-merchant/server.js。如需打包 VSIX 安装包,执行 npm run package。
💡 注意:本仓库快照由打包后的 VSIX 组装而成,直接携带编译好的
out/产物,源码说明见 src/README.md。
三、零资金沙盒演示:10 分钟跑通第一笔 AI Agent 支付 🎮
安装完成后,从活动栏打开 ixrail AgentPay 侧边栏,按以下 4 步完成首次支付:
- 一键搭建沙盒:点击 Set Up Sandbox Demo。它会自动创建
sandbox-demo的 Base Sepolia 钱包、应用仅限 localhost 的策略、启动认证 Broker 与内置模拟商户,并复制 Broker 令牌。 - 发起支付:点击 Pay endpoint,选择
sandbox-demo,目标地址使用http://127.0.0.1:4021/v1/weather。 - 观察完整流程:默认的
ixrail.simulateSettlement模拟结算模式下,扩展会完整执行策略校验 → 支付签名 → 重试请求 → 签名收据的闭环,不广播链上交易、不需要任何资金,模拟商户收取 0.05 USDC 并拒绝收据证明的重放。 - 查看收据:在 Agent 卡片中查看最近支付,或打开 All receipts 浏览完整签名收据台账。
想测试真实的 Base Sepolia USDC 转账?关闭 ixrail.simulateSettlement 设置,为钱包充值 Base Sepolia USDC 和足够的 ETH 作为 gas,然后重复支付即可。
四、配置支出策略:为 AI Agent 设置预算护栏 🛡️
每一笔 x402 结算在签名前都会先经过策略引擎评估,你可以为每个 Agent 单独配置:
| 控制项 | 作用 |
|---|---|
| 单笔限额 | 限制单次支付的最大金额 |
| 每日限额 | 按 UTC 日期累计的支出上限 |
| 每月限额 | 按 UTC 月份累计的支出上限 |
| 审批阈值 | 达到或超过该金额的请求,需 VS Code 内人工确认 |
| 白名单 | 允许接收支付的商户域名或收款地址 |
| 黑名单 | 一律拒绝的域名或地址(优先级最高) |
其他实用机制:
- 支出预留:已批准的额度会预留 10 分钟,防止并发请求绕过限额
- 撤销访问:Revoke access 可立即停止某 Agent 的全部支付并清除其预留,Restore 恢复时自动重新应用已保存策略
五、接入外部 AI Agent:MCP 服务器与本地 Broker 🔌
MCP stdio 方式
构建后运行 npm run mcp-server,即可得到无依赖的 stdio MCP 服务器(换行分隔的 JSON-RPC)。在扩展中执行 Copy MCP Configuration,可自动生成带正确路径的客户端配置条目:
{
"mcpServers": {
"ixrail-agentpay": {
"command": "node",
"args": ["/absolute/path/to/extension/out/mcp/server.js"],
"env": {
"IXRAIL_AGENTPAY_STORE": "/absolute/path/to/agentpay-store.json"
}
}
}
}
⚠️ MCP stdio 通道不使用 Bearer 令牌,进程启动本身就是信任边界——请限制能启动该进程和读取其存储文件的人。
本地 HTTP Broker 方式
从侧边栏启动 Broker,或构建后独立运行 npm run http-bridge。默认绑定 127.0.0.1:4022(仅回环地址),所有 /tools/* 请求需携带:
Authorization: Bearer <token>
Content-Type: application/json
常用环境变量速查:
| 变量 | 说明 | 默认值 |
|---|---|---|
IXRAIL_AGENTPAY_STORE |
独立 MCP/HTTP 进程使用的 JSON 存储 | ~/.ixrail-agentpay/store.json |
IXRAIL_HTTP_PORT |
Broker 端口(覆盖 ixrail.brokerPort) |
4022 |
IXRAIL_HTTP_TOKEN |
稳定的 Bearer 令牌,缺省时随机生成一次 | 随机 |
IXRAIL_MOCK_MERCHANT_PORT |
模拟商户端口 | 4021 |
可用工具路由:/tools/get_balance、/tools/request_payment、/tools/pay_x402_endpoint、/tools/create_spending_policy、/tools/get_receipt、/tools/revoke_agent_access。
六、常见问题快速排查(FAQ)❓
- 4021 / 4022 端口被占用:通过
IXRAIL_MOCK_MERCHANT_PORT或IXRAIL_HTTP_PORT(以及 VS Code 设置ixrail.brokerPort)更换端口,并同步更新支付 URL。 /tools/*返回 401 Unauthorized:确认发送了正确的Authorization: Bearer <token>;不带IXRAIL_HTTP_TOKEN重启会生成新令牌。- 支付被策略拒绝:依次检查撤销状态、白/黑名单、单笔限额、UTC 日/月累计支出、活跃预留以及调用方的
maxAmountUsd。 - 支付要求人工审批:金额达到或超过审批阈值。独立的 HTTP/stdio 进程没有 VS Code 审批界面,默认拒绝需要审批的结算。
- 主网转账被禁用:这是有意设计,需在显式设置
IXRAIL_ALLOW_MAINNET_PAYMENTS=1并重启后才允许真实的 Base 主网 USDC 转账。 - MCP 与 VS Code 看到的钱包不一致:两者默认使用不同存储后端,请把独立进程的
IXRAIL_AGENTPAY_STORE指向同一文件。
七、核心文件导航:深入了解项目 📚
| 文件 | 说明 |
|---|---|
| README.md | 项目完整说明:功能、安装、策略、安全与故障排查 |
| docs/ARCHITECTURE.md | 组件地图、x402 支付数据流与信任边界 |
| package.json | 扩展清单、贡献的命令/设置与 npm 脚本 |
| esbuild.js | 构建配置:4 个入口如何打包进 out/ |
| CHANGELOG.md | 版本历史(当前 0.2.6) |
| SECURITY.md | 安全漏洞私报渠道(请勿公开 issue) |
| CONTRIBUTING.md | 贡献流程与代码风格约定 |
| LICENSE | MIT 许可证 |
安全提示:钱包私钥、Broker 令牌和独立存储文件都应视为机密,不要提交到仓库或粘贴进日志。VS Code 内的密钥走 SecretStorage;独立进程的 JSON 存储文件仅依赖文件系统权限保护,请自行做好访问控制。
总结 🏁
按本文 7 个步骤,你只需要约 10 分钟就能:安装 ixrail AgentPay → 一键搭建零资金沙盒 → 完成首笔 x402 模拟支付 → 拿到可验证的签名收据。之后再为不同 Agent 配置差异化预算护栏,通过 MCP 或本地 Broker 接入你自己的 AI Agent——让 AI 自主花钱,但每一分钱都在你的规则之内。