stablepay-agentpay-dev

v0.3.21

Published

7 days ago

StablePay wallet, client-side DID registration, OWS/local signing, and payment tools for AI agents (OpenClaw, Claude Code, Codex, Cursor via MCP).

0High
0Medium
0Low

bubblevan

StablePay OpenClaw Plugin

StablePay 的 Agent 支付插件：把 StablePay 的链上支付能力注册成 20 个智能体可直接调用的工具。支持 OpenClaw、Claude Code、Codex、Cursor 等宿主，通过 OpenClaw plugin API 或 MCP（Model Context Protocol）暴露。

面向用户的快速开始 👇 见下方「产品侧：新手快速开始」
面向开发者的技术文档 👇 见下方「开发者侧：安装与配置」

产品侧：新手快速开始

你不需要配置环境变量、不需要理解 OWS/SDK/CLI/REST 的区别。安装后直接在对话里说一句话就行。

安装（一次性操作）

# 从 ClawHub 安装
openclaw plugins install clawhub:[email protected] --force --dangerously-force-unsafe-install

# 从 npm 直接安装
openclaw plugins install npm:[email protected] --force --dangerously-force-unsafe-install

openclaw gateway restart

初始化

在 OpenClaw / 飞书机器人对话里输入：

帮我初始化 StablePay 插件

智能体会自动调用 stablepay_onboard，依次完成：

✅ 自动生成本地加密密钥（无需你手动设置）
✅ 检查后端网关连通性
✅ 创建测试钱包（或按你的选择绑定已有钱包）
✅ 注册 DID 去中心化身份
✅ 设置默认支付限额（单笔 2 USDC，自动扣款 0.5 USDC）

全程智能体只会问你少量简单问题，例如「创建新钱包还是绑定已有钱包？」。

快速联调流程

初始化完成后，在对话里：

| 你想做什么 | 对智能体说 | |-----------|-----------| | 查余额 | "我的钱包余额是多少？" | | 查看官方商城商品 | "看看 StablePay 官方商城有哪些商品" | | 购买官方商城商品 | "帮我购买 Labubu 公仔" | | 直接支付给已知 Skill DID | "帮我付 1 USDC 给 did:solana:xxx 购买电子数字服务" | | 诊断状态 | "帮我检查 StablePay 插件状态" | | 查销售记录 | "查询这个商品的销售情况" |

MCP 快速开始（Claude Code / Codex / Cursor）

StablePay 同时是一个 MCP Server，通过 stdio JSON-RPC 暴露同样的 20 个工具。

安装

无需单独安装，MCP server 和 CLI 都在同一个 npm 包里：

npx stablepay-agentpay-dev doctor

配置 Claude Code

把下面配置加到 Claude Code 的 MCP 设置里（文件位置见 Claude Code 文档，通常是 ~/.claude/config.json 或 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "stablepay": {
      "command": "npx",
      "args": ["stablepay-agentpay-dev", "mcp"]
    }
  }
}

然后重启 Claude Code，输入：

帮我初始化 StablePay

Claude Code 会自动调用 stablepay_onboard 完成本地密钥、钱包、DID、限额设置。

配置 Codex / Cursor

Codex 与 Cursor 的 MCP 配置格式与 Claude Code 相同。把上面的 JSON 贴到对应设置里即可。

如果宿主只支持自定义命令（不支持 MCP），可直接调用 CLI：

npx stablepay-agentpay-dev merchant list
npx stablepay-agentpay-dev merchant buy labubu
npx stablepay-agentpay-dev pay --skill-did did:solana:... --skill-name ... --price 1.00

MCP 安全说明

MCP server 启动时会读取 ~/.stablepay-openclaw/master.key，进程拥有签名和支付能力。只添加到你信任的 MCP 配置里。
超过自动扣款阈值的支付会返回错误（isError: true）并要求用户显式确认。
可设置环境变量开启最严格模式，要求每笔支付都必须带 confirm_over_threshold: true：

{
  "mcpServers": {
    "stablepay": {
      "command": "npx",
      "args": ["stablepay-agentpay-dev", "mcp"],
      "env": {
        "STABLEPAY_MCP_STRICT_MODE": "1"
      }
    }
  }
}

开发者侧：安装与配置

ClawHub 安装

openclaw plugins install clawhub:stablepay-agentpay-dev
openclaw gateway restart

插件 slug：stablepay-agentpay-dev

环境变量说明

一般用户无需配置任何环境变量。以下仅为特殊场景参考：

| 变量 | 必需？ | 作用 | |------|--------|------| | STABLEPAY_PLUGIN_MASTER_KEY | ⚠️ 仅迁移旧 state 时需要 | 自定义密钥覆盖。正常情况下不需要，onboard 会自动生成本地 ~/.stablepay-openclaw/master.key | | STABLEPAY_FEE_PAYER_SOL | 可选 | 覆盖内置平台 hotwallet 公钥 | | STABLEPAY_OWS_PASSPHRASE | 可选 | OWS CLI/SDK 签名解锁口令 | | STABLEPAY_OWS_REST_API_KEY | 仅 ows-rest 必需 | OWS REST 签名服务 token |

开发联调

npm install
npm run check       # TypeScript 类型检查
npm run build       # 编译到 dist/
npm run eval:tooluse       # Mock 模式：无需 API key，验证工具选择逻辑
npm run eval:tooluse:llm   # LLM 模式：需要 OPENAI_API_KEY，验证真实 LLM 对 tool description 的理解
npm run check:manifest-tools  # 验证 manifest 工具声明一致性

LLM 模式使用

# ── OpenAI ──
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o-mini"
npm run eval:tooluse:llm

# ── Kimi (Moonshot Anthropic 兼容接口) ──
export ANTHROPIC_AUTH_TOKEN="这里填你的 Kimi Token"
export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
export ANTHROPIC_MODEL="kimi-k2.5"
npm run eval:tooluse:kimi

# ── 原生 Anthropic ──
export ANTHROPIC_AUTH_TOKEN="sk-ant-..."
npm run eval:tooluse:llm -- --provider anthropic

LLM 模式会用真实的大模型调用你的工具描述，检查：

LLM 是否在正确场景选择了正确的工具
tool description 是否足够清晰让 LLM 理解使用场景
是否出现 jargon 泄漏（LLM 主动向用户提及 MASTER_KEY、ows-sdk 等技术术语）

每个任务的 raw_response 会记录在 evals/traces/*.trace.json 中，可以审计 LLM 的原始输出。

Windows 开发 → WSL 部署调试流程

典型的开发流程：

Windows (D:\MyLab\StablePay\stablepay-openclaw-plugin)
  │  npm run build           ← 编译 TypeScript
  │  npm run eval:tooluse    ← 本地 mock 验证工具逻辑
  │  npm run eval:tooluse:llm ← 本地 LLM 验证 description
  │
  ├── openclaw plugins publish  ← 发布到 ClawHub
  │
  ▼
WSL (~/.openclaw/plugins/stablepay-agentpay-dev)
  │  openclaw plugins install clawhub:stablepay-agentpay-dev
  │  openclaw gateway restart
  │
  ▼ 在 OpenClaw / 飞书对话中测试

本地调试建议（不发布也能测）：

Windows 本机 mock 测试：npm run eval:tooluse 不需要任何外部依赖，3 个场景覆盖核心流程。
Windows 本机 LLM 测试：npm run eval:tooluse:llm 需要 API key 但不需要安装到 WSL，适合快速迭代 tool description。
WSL 完整集成测试：只有最终集成验证才需要发布到 ClawHub 并在 WSL 中重启网关。如果只是改工具描述或参数 schema，前两步足够了。

注意：npm pack --dry-run 显示的 tarball 只包含 dist/ 目录的编译产物和 openclaw.plugin.json，不包含 TypeScript 源码。scripts/ 和 evals/ 目录也不会被打包，它们是开发时工具，不影响运行时。

OpenClaw 配置示例

{
  "plugins": {
    "entries": {
      "stablepay-agentpay-dev": {
        "enabled": true,
        "config": {
          "backendBaseUrl": "https://ai.wenfu.cn"
        }
      }
    }
  }
}

工具清单（20 个）

| 工具名 | 类型 | 用途 | |--------|------|------| | stablepay_runtime_status | 核心 | 查看运行时状态 | | stablepay_create_local_wallet | 核心 | 创建新钱包 | | stablepay_bind_existing_wallet | 核心 | 绑定已有 OWS 钱包 | | stablepay_register_local_did | 核心 | 注册 DID | | stablepay_configure_payment_limits | 核心 | 设置支付限额 | | stablepay_build_payment_policy | 核心 | 构建支付策略 | | stablepay_sign_message | 核心 | 签名消息 | | stablepay_merchant_list_products | 官方商城 | 查询 https://ai.wenfu.cn/merchant 商品列表 | | stablepay_merchant_get_product | 官方商城 | 查询官方商城单个商品详情 | | stablepay_merchant_buy_product | 官方商城 | 按 sku 自动读取商家 402、支付并重试解锁 | | stablepay_pay_via_gateway | 核心 | 已知 seller skill_did 时直接支付（走网关 402 链路） | | stablepay_query_balance | 核心 | 查询 DID 余额 | | stablepay_query_sales | 核心 | 查询 Skill 销售记录 | | stablepay_doctor | 诊断 | 只读诊断（10 项健康检查） | | stablepay_onboard | 引导 | 状态机初始化向导 | | stablepay_operating_manual | 引导 | 返回工具选择、preflight、支付流程和安全约束说明 | | stablepay_generate_verify_link | Optional | 生成验证链接 | | stablepay_seed_mock_tweet | Optional | 模拟推文（测试用） | | stablepay_verify_x_mock | Optional | X 验证（测试用） | | stablepay_get_verify_status | Optional | 查询验证状态 |

兼容新版 OpenClaw Manifest 静态工具发现

本插件从 v0.3.17 起同时兼容：

新版：Manifest 静态声明

openclaw.plugin.json 新增三个字段：

{
  "activation": {
    "onStartup": true
  },
  "contracts": {
    "tools": ["stablepay_runtime_status", "stablepay_onboard", "...全部 20 个工具"]
  },
  "toolMetadata": {
    "stablepay_generate_verify_link": { "optional": true },
    "stablepay_seed_mock_tweet": { "optional": true },
    "stablepay_verify_x_mock": { "optional": true },
    "stablepay_get_verify_status": { "optional": true }
  }
}

contracts.tools：声明所有 20 个工具的所有权，让 OpenClaw 建立工具→插件的静态映射，无需加载所有插件的 runtime 就能知道工具属于谁。必填，必须与 src/index.ts 的 api.registerTool 完全一致。
toolMetadata：声明 optional 工具，让 OpenClaw 在 discovery 时直接隐藏未 opt in 的工具，无需加载 runtime 去问。
activation.onStartup：插件在 Gateway 启动时自动加载。

旧版：Runtime entry

runtime 入口仍然通过 package.json 的 openclaw.extensions 指向 ./dist/index.js：

{
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Gateway 2026.4.10 及之前版本完全不受影响。

校验

npm run check:manifest-tools

这个脚本会验证 contracts.tools 与 src/index.ts 的实际注册完全一致，以及 optional 标记一致。

技术架构

数据流

用户 / LLM
  │
  ▼
宿主（OpenClaw / Claude Code / Codex / Cursor）
  │
  ├── OpenClaw 插件入口 ── src/adapters/openclaw/index.ts
  ├── CLI 入口           ── src/cli.ts
  └── MCP Server 入口    ── src/mcp.ts（stdio JSON-RPC）
       │
       ▼
统一工具注册表（20 个 tools）── src/tools/registry.ts
       │
       ▼
StablePayRuntime + StablePayClient
       │
       ├── OWS SDK / CLI / REST（签名驱动）
       ├── AES-256-GCM 加密本地状态
       └── HTTP → StablePay API Gateway

关键设计

只读诊断：doctor 不写文件、不生成密钥、不修改 state
无感密钥管理：master.key 自动生成到 ~/.stablepay-openclaw/，用户无需手动设置
三层 OWS 暴露：ows-sdk 可用时自动隐藏 CLI/REST 细节
支付安全：单笔上限、自动扣款阈值、超额确认三层防护
Tool-use Eval：3 个场景的 mocking eval，可扩展对接真实 LLM
一码多宿主：同一套 src/tools/registry.ts 同时服务 OpenClaw、CLI 和 MCP，避免描述不同步
MCP 安全增强：超额或策略拒绝的支付以 isError: true 返回；支持 STABLEPAY_MCP_STRICT_MODE 强制每笔支付都需显式确认

开发者发布流程

1. 本地检查

npm run check              # TypeScript 类型检查
npm run eval:tooluse       # Mock 验证工具选择逻辑
npm run check:manifest-tools  # 校验 openclaw.plugin.json 工具声明
npm run build              # 打包 dist/
npm run check:dist-security   # 安全扫描

2. 版本号与包名

保持包名为 stablepay-agentpay-dev，版本号按 SemVer 递增：

npm version patch   # 或 minor / major

这会同步更新 package.json 和 package-lock.json。

3. 发布到 npm

npm publish --access public

发布后会触发 prepack 脚本自动执行 npm run build && node scripts/check-dist-security.mjs。

4. 发布到 ClawHub（OpenClaw 用户）

openclaw plugins publish

然后通知用户升级：

openclaw plugins install clawhub:stablepay-agentpay-dev@最新版本 --force --dangerously-force-unsafe-install
openclaw gateway restart

5. MCP 用户升级

MCP 用户只要 npm 包已发布，下次启动 host 时 npx stablepay-agentpay-dev mcp 会自动使用最新版本（npx 默认拉取最新）。如果想固定版本：

{
  "mcpServers": {
    "stablepay": {
      "command": "npx",
      "args": ["[email protected]", "mcp"]
    }
  }
}

注意事项

files 字段只包含 dist/、openclaw.plugin.json、README.md，源码不会进入 tarball。
dist/cli.cjs 是 CommonJS，用于 npx stablepay-agentpay-dev。
dist/index.js 是 ESM，用于 OpenClaw 插件加载。
修改 package.json 里的 version 后，记得同步更新 src/cli.ts 和 src/mcp.ts 里的版本号（目前需要手动保持一致）。