Skip to content

Commit 3da17ca

Browse files
tenequmtenequm
committed
docs(skill): add OpenClaw plugin setup reference
- Create references/openclaw-plugin.md with full step-by-step guide: install, wallet setup, provider/model config, troubleshooting - Include all 15 current inference.surf.cascade.fyi models - Trim SKILL.md OpenClaw section to brief pointer to reference doc
1 parent 893e1f8 commit 3da17ca

2 files changed

Lines changed: 143 additions & 6 deletions

File tree

‎packages/x402-proxy/skills/SKILL.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -165,14 +165,16 @@ stdout = response body, stderr = payment info. Pipes, redirects, and `jq` all wo
165165

166166
## OpenClaw Plugin
167167

168-
x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin. Install it to give your OpenClaw gateway automatic x402 payment capabilities:
168+
x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin for automatic x402 payments, wallet management, and pay-per-use inference proxying. For full installation, provider/model configuration, and troubleshooting, read `references/openclaw-plugin.md`.
169169

170-
- `x_balance` tool - check wallet SOL/USDC balances
171-
- `x_payment` tool - call any x402-enabled endpoint with automatic payment
172-
- `/x_wallet` command - wallet status, send USDC, transaction history
173-
- HTTP route proxy (`/x402/*`) - proxies requests to upstream x402 endpoints with payment
170+
Quick install:
174171

175-
Configure in your OpenClaw plugin settings with `providers` (upstream x402 endpoints and models) and optionally `keypairPath` or use the standard `X402_PROXY_WALLET_MNEMONIC` env var.
172+
```bash
173+
openclaw plugins install x402-proxy
174+
npx x402-proxy setup # creates wallet if needed
175+
```
176+
177+
Registers: `x_balance` tool, `x_payment` tool, `/x_wallet` command, `/x402/*` HTTP route for inference proxying.
176178

177179
## Library API
178180

‎packages/x402-proxy/skills/references/openclaw-plugin.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# OpenClaw Plugin Setup
2+
3+
x402-proxy ships as an [OpenClaw](https://openclaw.dev) plugin. Gives your gateway automatic x402 payment, wallet management, and pay-per-use inference proxying via Solana USDC.
4+
5+
## What it registers
6+
7+
- **`x_balance` tool** - check wallet SOL/USDC balances, daily spend, available funds
8+
- **`x_payment` tool** - call any x402-enabled endpoint with automatic payment (params: `url`, `method`, `params`, `headers`)
9+
- **`/x_wallet` command** - wallet status dashboard, `send <amount|all> <address>`, `history [page]`
10+
- **HTTP route `/x402/*`** - proxies requests to upstream inference endpoints with payment, tracks token usage and cost
11+
12+
## Step 1: Install the plugin
13+
14+
```bash
15+
openclaw plugins install x402-proxy
16+
```
17+
18+
This downloads from npm, validates `openclaw.plugin.json`, and installs to `~/.openclaw/extensions/x402-proxy/`.
19+
20+
## Step 2: Configure wallet
21+
22+
The plugin resolves a Solana wallet using the same cascade as the CLI:
23+
24+
1. `keypairPath` in plugin config (solana-keygen JSON file)
25+
2. `X402_PROXY_WALLET_SOLANA_KEY` env var (base58 or JSON array)
26+
3. `X402_PROXY_WALLET_MNEMONIC` env var (BIP-39, derives both Solana and EVM)
27+
4. `~/.config/x402-proxy/wallet.json` (auto-created by `npx x402-proxy setup`)
28+
29+
Easiest path - run setup first, then the plugin picks up the wallet automatically:
30+
31+
```bash
32+
npx x402-proxy setup
33+
```
34+
35+
Or set an explicit keypair in plugin config (step 3).
36+
37+
## Step 3: Configure providers and models
38+
39+
Add the plugin config to your `openclaw.json` (or via `openclaw config edit`):
40+
41+
```json
42+
{
43+
"plugins": {
44+
"entries": {
45+
"x402-proxy": {
46+
"config": {
47+
"providers": {
48+
"surf-inference": {
49+
"baseUrl": "/x402/v1",
50+
"upstreamUrl": "https://inference.surf.cascade.fyi",
51+
"models": [
52+
{ "id": "anthropic/claude-opus-4.6", "name": "Claude Opus 4.6", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.015, "output": 0.075, "cacheRead": 0.0015, "cacheWrite": 0.01875 }, "contextWindow": 200000 },
53+
{ "id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0.0003, "cacheWrite": 0.00375 }, "contextWindow": 200000 },
54+
{ "id": "anthropic/claude-opus-4.5", "name": "Claude Opus 4.5", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.015, "output": 0.075, "cacheRead": 0.0015, "cacheWrite": 0.01875 }, "contextWindow": 200000 },
55+
{ "id": "anthropic/claude-sonnet-4.5", "name": "Claude Sonnet 4.5", "maxTokens": 200000, "reasoning": true, "input": ["text", "image"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0.0003, "cacheWrite": 0.00375 }, "contextWindow": 200000 },
56+
{ "id": "x-ai/grok-4.20-beta", "name": "Grok 4.20 Beta", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
57+
{ "id": "x-ai/grok-4.20-multi-agent-beta", "name": "Grok 4.20 Multi-Agent", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
58+
{ "id": "x-ai/grok-4.1-fast", "name": "Grok 4.1 Fast", "maxTokens": 131072, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
59+
{ "id": "x-ai/grok-4.20-beta:online", "name": "Grok 4.20 Beta (Online)", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.005, "output": 0.025, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
60+
{ "id": "x-ai/grok-4.20-multi-agent-beta:online", "name": "Grok 4.20 Multi-Agent (Online)", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.005, "output": 0.025, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
61+
{ "id": "x-ai/grok-4.1-fast:online", "name": "Grok 4.1 Fast (Online)", "maxTokens": 131072, "reasoning": false, "input": ["text"], "cost": { "input": 0.003, "output": 0.015, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
62+
{ "id": "minimax/minimax-m2.7", "name": "MiniMax M2.7", "maxTokens": 1000000, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 1000000 },
63+
{ "id": "minimax/minimax-m2.5", "name": "MiniMax M2.5", "maxTokens": 1000000, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 1000000 },
64+
{ "id": "moonshotai/kimi-k2.5", "name": "Kimi K2.5", "maxTokens": 131072, "reasoning": true, "input": ["text"], "cost": { "input": 0.002, "output": 0.008, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072 },
65+
{ "id": "z-ai/glm-5", "name": "GLM-5", "maxTokens": 128000, "reasoning": false, "input": ["text"], "cost": { "input": 0.001, "output": 0.005, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000 },
66+
{ "id": "qwen/qwen-2.5-7b-instruct", "name": "Qwen 2.5 7B Instruct", "maxTokens": 32768, "reasoning": false, "input": ["text"], "cost": { "input": 0.0003, "output": 0.001, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 32768 }
67+
]
68+
}
69+
}
70+
}
71+
}
72+
}
73+
}
74+
}
75+
```
76+
77+
### Config fields
78+
79+
| Field | Description |
80+
|-------|-------------|
81+
| `providers.<name>.baseUrl` | Route path registered in OpenClaw (e.g., `/x402/v1`) |
82+
| `providers.<name>.upstreamUrl` | Actual upstream endpoint (e.g., `https://inference.surf.cascade.fyi`) |
83+
| `providers.<name>.models[]` | Model catalog array |
84+
| `keypairPath` | Optional path to solana-keygen JSON file (overrides wallet resolution) |
85+
| `rpcUrl` | Solana RPC URL (defaults to mainnet public endpoints with failover) |
86+
| `dashboardUrl` | URL linked from `/x_wallet` dashboard |
87+
88+
### Model entry fields
89+
90+
| Field | Type | Description |
91+
|-------|------|-------------|
92+
| `id` | string | Model identifier (e.g., `anthropic/claude-opus-4.6`) |
93+
| `name` | string | Display name |
94+
| `maxTokens` | number | Max context length |
95+
| `reasoning` | boolean | Supports extended thinking |
96+
| `input` | string[] | Input modalities: `["text"]` or `["text", "image"]` |
97+
| `cost.input` | number | USDC per 1K input tokens |
98+
| `cost.output` | number | USDC per 1K output tokens |
99+
| `cost.cacheRead` | number | USDC per 1K cached read tokens |
100+
| `cost.cacheWrite` | number | USDC per 1K cache write tokens |
101+
| `contextWindow` | number | Full context window size |
102+
103+
## Step 4: Restart gateway and verify
104+
105+
```bash
106+
openclaw gateway restart
107+
openclaw models # verify models appear
108+
```
109+
110+
## How it works
111+
112+
1. Plugin boots, loads wallet via the resolution cascade
113+
2. Registers each provider from config into OpenClaw's model catalog (API type: `openai-completions`, no auth required)
114+
3. HTTP route `/x402/*` intercepts inference requests, strips prefix, proxies to `upstreamUrl`
115+
4. On 402 response, auto-signs a Solana USDC payment and retries
116+
5. SSE streaming responses are parsed for token usage and logged to `~/.config/x402-proxy/history.jsonl`
117+
6. Tools and command are available to all agents on the gateway
118+
119+
## Fetching latest models
120+
121+
The model list on `inference.surf.cascade.fyi` changes over time. Fetch the current catalog:
122+
123+
```bash
124+
npx x402-proxy --protocol mpp --network solana \
125+
https://inference.surf.cascade.fyi/v1/models
126+
```
127+
128+
Then update the `models` array in your plugin config accordingly.
129+
130+
## Troubleshooting
131+
132+
- **Models don't appear in `openclaw models`** - the plugin uses a `catalog` hook (not `models` field). Make sure you're on x402-proxy >= 0.8.5.
133+
- **"no wallet found" in logs** - run `npx x402-proxy setup` or set `X402_PROXY_WALLET_MNEMONIC` env var before starting the gateway.
134+
- **402 errors on inference** - check wallet has USDC balance: use `x_balance` tool or `npx x402-proxy wallet`.
135+
- **Gateway cold start slow** - normal on small VMs (~72s). The `x402-wallet` service eagerly loads the wallet during boot.

0 commit comments

Comments
 (0)