如何快速上手ixrail AgentPay:10分钟安装配置AI Agent支付工具完整教程

原创2026-10-15 21:26:201,612 阅读

如何快速上手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 步完成首次支付:

  1. 一键搭建沙盒:点击 Set Up Sandbox Demo。它会自动创建 sandbox-demo 的 Base Sepolia 钱包、应用仅限 localhost 的策略、启动认证 Broker 与内置模拟商户,并复制 Broker 令牌。
  2. 发起支付:点击 Pay endpoint,选择 sandbox-demo,目标地址使用 http://127.0.0.1:4021/v1/weather。
  3. 观察完整流程:默认的 ixrail.simulateSettlement 模拟结算模式下,扩展会完整执行策略校验 → 支付签名 → 重试请求 → 签名收据的闭环,不广播链上交易、不需要任何资金,模拟商户收取 0.05 USDC 并拒绝收据证明的重放。
  4. 查看收据:在 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 自主花钱,但每一分钱都在你的规则之内。

登录后查看全文
ixrail