StablePay OpenClaw Plugin
OpenClaw plugin that handles the client-side wallet, signing, and payment-policy side of the StablePay flow.
Verified state
stablepay_runtime_status confirmed working as of 2026-03-31:
{
"requested_driver": "auto",
"active_driver": "local-dev",
"available_drivers": ["local-dev"],
"local_state_path": "/home/bubblevan/.stablepay-openclaw/stablepay-local-state.enc",
"has_wallet": false,
"wallet": null,
"payment_config": null,
"policy": null,
"notes": [
"OWS Node SDK could not be loaded in this environment. On the current Windows machine, the official package does not ship a win32 native binding yet.",
"The plugin will use a local AES-256-GCM encrypted state file as the current development fallback. This is suitable for local OpenClaw demos, but it is not the final OWS custody model."
]
}
DID 与私钥模型（重要）
| API | 用途 | 私钥位置 |
|---|
| **`POST /api/v1/did`**（默认 `didRegisterPath`） | **契约主路径**（PRD/tech）；`stablepay_register_local_did` | 客户端 / OWS Vault；服务端只存公钥 |
| **`POST /api/v1/did/register`** | 与上一行**同一逻辑**的兼容别名 | 同上 |
服务端不生成、不托管用户私钥。路由说明见 api-gateway/docs/did-flow.md。
Runtime model
| Driver | When active | Notes |
|---|
| `ows-sdk` | `@open-wallet-standard/core` 可加载 | In-process 签名（Linux/macOS 等） |
| `ows-rest` | 配置了 `owsRestBaseUrl` + `STABLEPAY_OWS_REST_API_KEY`（或自定义 env） | HTTP `SignMessageRequest` → hex `signature` |
| `ows-cli` / `wsl-ows` | `ows` 在 PATH 且可选用 | 子进程 `ows sign message --json` |
| `local-dev` | 兜底 | AES-256-GCM 加密状态文件 `~/.stablepay-openclaw/` |
auto 优先级：ows-sdk →（若配置了 REST 且存在 API key）ows-rest → ows-cli → local-dev。Windows 上常无 OWS 原生绑定，会落到 local-dev 或你在 WSL 里用 ows-cli。
WSL 端到端步骤见 docs/ows-wsl-e2e.md。
Installation
WSL (required — do not install from /mnt/d/)
OpenClaw blocks plugins installed from NTFS-mounted paths (/mnt/d/, /mnt/c/, etc.) because Windows NTFS shows mode=777 in WSL and OpenClaw treats world-writable paths as untrusted.
Copy the plugin to a Linux-native path, build it, then install:
cp -r /mnt/d/mylab/stablepay/stablepay-openclaw-plugin ~/stablepay-openclaw-plugin
cd ~/stablepay-openclaw-plugin
chmod -R 755 .
npm install
npm run build # compiles src/ → dist/
openclaw plugins install --link ~/stablepay-openclaw-plugin
openclaw gateway restart
After any source change, rebuild and reinstall:
cd ~/stablepay-openclaw-plugin
npm run build
openclaw plugins install --link ~/stablepay-openclaw-plugin
openclaw gateway restart
Permanent fix (optional)
To avoid the copy and let OpenClaw accept /mnt/d/ paths, configure WSL to mount with proper permissions:
sudo tee -a /etc/wsl.conf > /dev/null << 'EOF'
[automount]
options = "metadata,umask=022,fmask=111"
EOF
Then restart WSL from Windows PowerShell:
wsl --shutdown
After that you can install directly from the Windows path.
Required environment variable
Set STABLEPAY_PLUGIN_MASTER_KEY before using the local wallet runtime. The plugin uses this to derive the AES-256-GCM key for stablepay-local-state.enc.
# bash / WSL
export STABLEPAY_PLUGIN_MASTER_KEY="replace-with-a-long-random-secret"
# PowerShell
$env:STABLEPAY_PLUGIN_MASTER_KEY = "replace-with-a-long-random-secret"
If this variable is not set, stablepay_create_local_wallet will fail.
Optional (only needed if you run a supported OWS SDK runtime):
export STABLEPAY_OWS_PASSPHRASE="..."
Plugin config (~/.openclaw/openclaw.json)
All fields are optional. The plugin falls back to the defaults shown below if config is absent.
{
"plugins": {
"entries": {
"stablepay-mock-plugin": {
"enabled": true,
"config": {
"backendBaseUrl": "http://127.0.0.1:28080",
"verifyPageBaseUrl": "http://127.0.0.1:3000/verify",
"owsRuntime": "auto",
"walletNamePrefix": "stablepay",
"didRegisterPath": "/api/v1/did",
"owsRestBaseUrl": "",
"owsRestSignPath": "/v1/sign/message",
"owsRestWalletId": ""
}
}
}
}
}
backendBaseUrl defaults to http://127.0.0.1:8080 if omitted（Docker 联调请改为 Gateway 端口，如 28080）。
Tools
Local wallet runtime (new)
| Tool | What it does |
|---|
| `stablepay_runtime_status` | Show active driver, wallet presence, state path, payment config, policy |
| `stablepay_create_local_wallet` | Generate an Ed25519 keypair, encrypt and save to local state file |
| `stablepay_register_local_did` | POST the local public key to `backendBaseUrl/didRegisterPath` to create a backend DID record |
| `stablepay_configure_payment_limits` | Save single-purchase limit and auto-purchase threshold to local state |
| `stablepay_build_payment_policy` | Assemble a payment policy manifest from local wallet + limits |
| `stablepay_sign_message` | Sign a message with the local private key (key never leaves the state file) |
| `stablepay_execute_paid_skill_demo` | Exercise the `verify → 402 → pay → retry → 200` chain against `showmethemoney-skill/demo-backend` |
Test sequence
Smoke test (run first)
Call stablepay_runtime_status and return only the structured result.
Call stablepay_create_local_wallet. Create one local StablePay wallet and show the returned address or wallet summary.
Call stablepay_runtime_status and summarize only the wallet-related fields.
Expected after create_local_wallet: has_wallet: true, wallet not null.
A2 prep flow
Call stablepay_create_local_wallet. Create one local StablePay wallet.
Call stablepay_register_local_did for the current local wallet and return the backend response.
Call stablepay_configure_payment_limits. Set single purchase limit to 5 USDC and auto-purchase threshold to 1 USDC.
Call stablepay_build_payment_policy and return the generated policy manifest.
Call stablepay_sign_message. Sign the message: StablePay local signing smoke test.
B demo flow (paid skill)
Start the demo backend first:
cd showmethemoney-skill/demo-backend
npm install && npm start
Then in OpenClaw:
Call stablepay_execute_paid_skill_demo and show the full payment flow result.
Expected chain: verify → 402 Payment Required → sign + pay → retry → 200 OK.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|
| `world-writable path (mode=777)` | Installing from `/mnt/d/` | Copy to `~/` first |
| `must have required property 'backendBaseUrl'` | Old `openclaw.plugin.json` with `"required": ["backendBaseUrl"]` | Pull latest; old schema is fixed |
| `stablepay_create_local_wallet` fails | `STABLEPAY_PLUGIN_MASTER_KEY` not set | Set the env var and restart gateway |
| `stablepay_register_local_did` fails | Wrong `backendBaseUrl` or `didRegisterPath` | Check plugin config and that api-gateway is running |
| `stablepay_sign_message` fails | Local runtime issue, not a backend issue | Check state file exists and key env var is correct |
| `stablepay_execute_paid_skill_demo` fails | demo-backend not running | Start `showmethemoney-skill/demo-backend` first |
Development
npm install
npm run check # TypeScript type check, no output
npm run build # compile src/ → dist/, required before install
OpenClaw loads dist/index.js (compiled output). After every source change you need to rebuild and reinstall the plugin before the changes take effect in the gateway.