Policy Proxy Wallet

策略代理钱包

让AI代理在不持有密钥的情况下花钱。

一个MCP服务器，使AI代理能够 x402 支付与政策执行。代理从不接触私钥——本地代理在签署任何交易之前会评估支出规则。

# Install
npm install

# Create wallet (one time)
WALLET_PASSPHRASE=your-secret npm run init-wallet

# Run the MCP server
WALLET_PASSPHRASE=your-secret npm run dev

在Base上用USDC为钱包地址充值，然后您的代理人可以支付x402服务。

______________________________________________________________________

快速开始

1.安装并创建钱包

git clone https://github.com/csmoove530/policy-proxy-wallet.git
cd policy-proxy-wallet
npm install

# Create an encrypted wallet (saves to config/keystore.json)
WALLET_PASSPHRASE=your-secret npm run init-wallet

输出：

Wallet created successfully.
Address: 0x1234...abcd
Keystore: ~/.openclaw/workspace/policy-proxy-wallet/config/keystore.json

2.为钱包充值

将少量USDC发送到您的钱包地址 基础 网络。

3.添加到克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "policy-wallet": {
      "command": "node",
      "args": ["--import", "tsx", "/path/to/policy-proxy-wallet/src/server.ts"],
      "env": {
        "WALLET_PASSPHRASE": "your-secret"
      }
    }
  }
}

4.首次付款

让克劳德使用x402服务。代理人打电话来 policy_wallet_pay:

{
  "serviceUrl": "https://api.example.com/generate",
  "payTo": "0xServiceAddress...",
  "amount": "50000",
  "description": "Generate an image"
}

答复：

{
  "status": "paid",
  "txHash": "0xabc123...",
  "from": "0xYourWallet...",
  "to": "0xServiceAddress...",
  "amount": "50000",
  "amountUSD": 0.05
}

______________________________________________________________________

运作原理

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  AI Agent   │────▶│  Policy Proxy    │────▶│  Base (L2)  │
│  (Claude)   │     │  Wallet (MCP)    │     │  USDC       │
└─────────────┘     └──────────────────┘     └─────────────┘
                            │
                    ┌───────┴───────┐
                    │               │
              ┌─────▼─────┐   ┌─────▼─────┐
              │  Policy   │   │  Keystore │
              │  Engine   │   │  (local)  │
              └───────────┘   └───────────┘

1. 代理人通过MCP工具调用请求付款
2. 策略引擎根据支出规则进行评估
3. 如果获得批准，代理人签署并广播交易
4. 代理收到tx哈希确认

代理人 永远看不到私钥。它只看到批准/拒绝决定。

______________________________________________________________________

政策规则

策略引擎按顺序评估请求。第一次否认获胜。

policy.json示例

{
  "version": "1.0",
  "enabled": true,
  "limits": {
    "perTransaction": { "maxAmountUSD": 0.10 },
    "perSession": { "maxAmountUSD": 5.00, "windowSeconds": 86400 },
    "cooldown": { "maxTransactions": 10, "windowSeconds": 60 }
  },
  "autoApprove": {
    "enabled": true,
    "maxAmountUSD": 0.05
  },
  "whitelist": {
    "enabled": false,
    "domains": ["api.example.com", "trusted-service.io"],
    "categories": ["image-generation", "search"]
  },
  "humanApproval": {
    "enabled": true,
    "timeoutSeconds": 300,
    "defaultOnTimeout": "deny"
  }
}

______________________________________________________________________

MCP工具

保单_钱包_支付

提交付款请求。进行政策评估。

请求：

{
  "serviceUrl": "https://api.example.com/generate",
  "payTo": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "50000",
  "description": "Generate product image",
  "category": "image-generation"
}

成功响应：

{
  "status": "paid",
  "txHash": "0x1234567890abcdef...",
  "from": "0xYourWallet...",
  "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "50000",
  "amountUSD": 0.05
}

拒绝回复：

{
  "status": "denied",
  "reason": "Exceeds per-tx cap: $0.15 > $0.10"
}

policy_wallet_balance

检查USDC余额和剩余的每日津贴。

答复：

{
  "address": "0xYourWallet...",
  "balanceUSDC": "4.532100",
  "dailyAllowance": {
    "limit": 5.0,
    "spent": 0.15,
    "remaining": 4.85
  },
  "autoApproveMax": 0.05
}

policy_wallet_status

查看当前策略配置和支出状态。

答复：

{
  "policyEnabled": true,
  "frozen": false,
  "limits": {
    "perTransaction": { "max": 0.10 },
    "daily": { "max": 5.0, "spent": 0.15, "remaining": 4.85 },
    "cooldown": { "maxPerMinute": 10, "currentCount": 2 }
  },
  "autoApprove": { "enabled": true, "maxAmountUSD": 0.05 },
  "whitelist": { "enabled": false, "domains": [], "categories": [] },
  "humanApproval": true,
  "pendingApprovals": 0
}

policy_wallet_history

查看最近的交易记录。

请求：

{ "limit": 5 }

答复：

[
  {
    "id": "abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "serviceUrl": "https://api.example.com/generate",
    "amountUSD": 0.05,
    "finalOutcome": "paid",
    "txHash": "0x1234..."
  }
]

policy_wallet_approve

批准或拒绝待处理的人工批准请求。

请求：

{
  "approvalId": "abc123",
  "approved": true
}

答复：

{ "status": "processed", "approved": true }

______________________________________________________________________

错误处理

验证错误

{
  "status": "error",
  "validation": "payTo: payTo must be a valid Ethereum address"
}

政策否认

{
  "status": "denied",
  "reason": "Would exceed daily cap: $5.15 > $5.00 (already spent: $4.95)"
}

交易错误

{
  "status": "error",
  "error": "insufficient funds for gas"
}

常见的拒绝理由

______________________________________________________________________

配置

环境变量

文件位置

policy-proxy-wallet/
├── config/
│   ├── keystore.json    # Encrypted wallet (never commit!)
│   └── policy.json      # Policy rules (edit this)
├── data/
│   └── audit.db         # Transaction history
└── src/
    └── server.ts        # MCP server

______________________________________________________________________

安全模型

代理可以做什么

• 请求付款（根据政策）
• 检查余额和历史记录
• 提交审批回复

代理人不能做什么

• 访问私钥
• 修改策略规则
• 绕过支出限制
• 批准自己的请求

设计原则

1. 纵深防御：多个独立限制（每交易、每日、冷却时间）
2. 出故障时自动关闭的：默认情况下拒绝未知状态
3. 审核一切：记录到SQLite的每个请求
4. 人为干预：通过policy.json立即冻结钱包

______________________________________________________________________

发展

# Run tests
npm test

# Build TypeScript
npm run build

# Run in development
WALLET_PASSPHRASE=test npm run dev

项目结构

src/
├── server.ts           # MCP server + tool handlers
├── policy/
│   ├── engine.ts       # Policy evaluation (pure function)
│   ├── ledger.ts       # In-memory spending tracker
│   └── types.ts        # TypeScript types + Zod schemas
├── custody/
│   └── local-wallet.ts # Keystore + ethers.js signing
├── approval/
│   └── pending.ts      # Human approval queue
├── audit/
│   └── log.ts          # SQLite audit trail
├── config/
│   └── loader.ts       # Policy config loader
└── cli/
    └── init-wallet.ts  # Wallet creation CLI

______________________________________________________________________

许可证

麻省理工学院