@blockrun/clawrouter 0.12.267 → 0.12.268
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +147 -21
- package/dist/cli.js +664 -157
- package/dist/index.d.ts +58 -11
- package/dist/index.js +326 -90
- package/docs/configuration.md +102 -9
- package/openclaw.plugin.json +9 -0
- package/package.json +3 -2
package/docs/configuration.md
CHANGED
|
@@ -5,6 +5,8 @@ Complete reference for ClawRouter configuration options.
|
|
|
5
5
|
## Table of Contents
|
|
6
6
|
|
|
7
7
|
- [Environment Variables](#environment-variables)
|
|
8
|
+
- [API Key Authentication](#api-key-authentication)
|
|
9
|
+
- [Environment Variable Reference](#environment-variable-reference)
|
|
8
10
|
- [Wallet Configuration](#wallet-configuration)
|
|
9
11
|
- [Wallet Backup & Recovery](#wallet-backup--recovery)
|
|
10
12
|
- [Proxy Settings](#proxy-settings)
|
|
@@ -19,15 +21,106 @@ Complete reference for ClawRouter configuration options.
|
|
|
19
21
|
|
|
20
22
|
## Environment Variables
|
|
21
23
|
|
|
22
|
-
| Variable | Default | Description
|
|
23
|
-
| --------------------------- | ------------------------------------- |
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
24
|
+
| Variable | Default | Description |
|
|
25
|
+
| --------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
|
+
| `BLOCKRUN_API_KEY` | - | BlockRun API key (`brk_live_…`). Pays from card-funded account credit via `api.blockrun.ai` instead of a wallet. Takes precedence over every wallet source. |
|
|
27
|
+
| `BLOCKRUN_API_BASE_URL` | `https://api.blockrun.ai` | Override the API-key gateway (staging deploys only). |
|
|
28
|
+
| `BLOCKRUN_WALLET_KEY` | - | Explicit Base wallet override (hex, 0x-prefixed). |
|
|
29
|
+
| `BLOCKRUN_PROXY_PORT` | `8402` | Port for the local x402 proxy server. |
|
|
30
|
+
| `CLAWROUTER_SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint for USDC balance checks. |
|
|
31
|
+
| `CLAWROUTER_DISABLED` | `false` | Set to `true` to disable smart routing (pass requests through as-is). |
|
|
32
|
+
| `CLAWROUTER_WORKER` | - | Set to `1` to enable Worker Mode (earn USDC by running health checks). |
|
|
33
|
+
| `CLAWROUTER_DEBUG_HEADERS` | (on) | Set to `off`/`false`/`0` to suppress the `x-clawrouter-*` debug response headers. |
|
|
34
|
+
| `BLOCKRUN_WEB_SEARCH` | (auto-enabled) | Set to `off` to disable BlockRun's Exa web search provider registration. |
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## API Key Authentication
|
|
39
|
+
|
|
40
|
+
ClawRouter has two ways to pay BlockRun, and they are mutually exclusive per
|
|
41
|
+
process:
|
|
42
|
+
|
|
43
|
+
| | Wallet (default) | API key |
|
|
44
|
+
| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
45
|
+
| Credential | An EVM/Solana private key held locally | `brk_live_…`, issued at [user.blockrun.ai](https://user.blockrun.ai) |
|
|
46
|
+
| Gateway | `blockrun.ai/api` (Base), `sol.blockrun.ai/api` (Solana) | `api.blockrun.ai` |
|
|
47
|
+
| Wire auth | An x402 signature per request | `Authorization: Bearer brk_live_…` |
|
|
48
|
+
| Funding | USDC you send to the wallet | Credit card top-up on the portal |
|
|
49
|
+
| Out of money | Local balance check → free-model fallback | Gateway answers `402 insufficient_quota` |
|
|
50
|
+
|
|
51
|
+
**An API key wins whenever one is present.** A machine holding both a legacy
|
|
52
|
+
wallet and a key the user just added means "bill my account", not "keep spending
|
|
53
|
+
my USDC". Nothing is deleted — `clawrouter logout` puts the wallet back in
|
|
54
|
+
charge.
|
|
55
|
+
|
|
56
|
+
### Resolution order
|
|
57
|
+
|
|
58
|
+
1. `BLOCKRUN_API_KEY` environment variable
|
|
59
|
+
2. BlockRun Core — `~/.blockrun/.api-key`, shared with other BlockRun products
|
|
60
|
+
3. Legacy ClawRouter location — `~/.openclaw/blockrun/api-key`
|
|
61
|
+
4. The OpenClaw plugin's `apiKey` config value (checked first inside the plugin)
|
|
62
|
+
|
|
63
|
+
A file that exists but does not hold a `brk_`-prefixed value is reported and
|
|
64
|
+
skipped rather than sent upstream — a malformed credential otherwise surfaces as
|
|
65
|
+
an unexplained 401 on every request.
|
|
66
|
+
|
|
67
|
+
### Commands
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
clawrouter login brk_live_... # save to ~/.blockrun/.api-key (mode 0600)
|
|
71
|
+
clawrouter login # prompt for the key instead
|
|
72
|
+
clawrouter logout # delete stored keys, fall back to the wallet
|
|
73
|
+
clawrouter status # shows the mode, gateway, and masked key
|
|
74
|
+
clawrouter doctor # verifies the key against api.blockrun.ai
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Behaviour in API-key mode
|
|
78
|
+
|
|
79
|
+
- **No wallet is created or read.** `startProxy` skips the x402 client, the EVM
|
|
80
|
+
and Solana signers, and the spend-policy pre-sign hook entirely — there is
|
|
81
|
+
nothing to sign. `clawrouter doctor` will not generate one either.
|
|
82
|
+
- **No payment chain.** `/health` reports `authMode: "api-key"` with a masked
|
|
83
|
+
key and no `paymentChain`, `wallet` or `solana` field. Two ClawRouters on the
|
|
84
|
+
same port refuse to reuse each other across modes, the same way they already
|
|
85
|
+
refuse across chains.
|
|
86
|
+
- **No local balance gate.** The gateway holds the books and publishes no
|
|
87
|
+
key-readable balance, so ClawRouter does not guess one: it makes the call, and
|
|
88
|
+
a 402 with `insufficient_quota` is the answer when credit runs out. The free
|
|
89
|
+
models remain free and need no credit.
|
|
90
|
+
- **Endpoint coverage.** `api.blockrun.ai` currently serves `/v1/chat/completions`,
|
|
91
|
+
`/v1/messages`, `GET /v1/models` and `GET /v1/images/models`. Media and partner
|
|
92
|
+
endpoints stay wallet-only until BlockRun publishes them on the API-key rail;
|
|
93
|
+
ClawRouter passes every path through and rewrites the gateway's
|
|
94
|
+
`Unsupported endpoint` 404 into an explanation, so new services work the day
|
|
95
|
+
they ship with no ClawRouter release.
|
|
96
|
+
- **Routing is unchanged.** Model ids, aliases, the 15-dimension classifier, the
|
|
97
|
+
fallback chains, `/exclude`, `maxCostPerRun` and the response cache all behave
|
|
98
|
+
identically.
|
|
99
|
+
- **`clawrouter policy` limits are NOT enforced.** The spend windows
|
|
100
|
+
(`perRequest`/`hourly`/`daily`/`session`) and the payee/network/asset lists are
|
|
101
|
+
checked in the x402 pre-sign hook, which does not run when nothing is signed.
|
|
102
|
+
Your BlockRun account balance is the cap. ClawRouter warns at startup if any
|
|
103
|
+
limit is configured, so a disabled cap is never silent. `maxCostPerRun` is
|
|
104
|
+
unaffected — it is enforced by the router.
|
|
105
|
+
|
|
106
|
+
### Using the key without ClawRouter
|
|
107
|
+
|
|
108
|
+
The same key works against `api.blockrun.ai` from any OpenAI-compatible client
|
|
109
|
+
(`Authorization: Bearer`) or Anthropic client (`x-api-key`):
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
curl https://api.blockrun.ai/v1/chat/completions \
|
|
113
|
+
-H "Authorization: Bearer brk_live_..." \
|
|
114
|
+
-H "Content-Type: application/json" \
|
|
115
|
+
-d '{"model": "anthropic/claude-sonnet-5", "messages": [{"role": "user", "content": "hello"}]}'
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Going through ClawRouter is what adds smart routing, fallback chains, the
|
|
119
|
+
response cache and local spend controls.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Environment Variable Reference
|
|
31
124
|
|
|
32
125
|
### BLOCKRUN_WALLET_KEY
|
|
33
126
|
|
package/openclaw.plugin.json
CHANGED
|
@@ -43,6 +43,10 @@
|
|
|
43
43
|
"configSchema": {
|
|
44
44
|
"type": "object",
|
|
45
45
|
"properties": {
|
|
46
|
+
"apiKey": {
|
|
47
|
+
"type": "string",
|
|
48
|
+
"description": "BlockRun API key (brk_live_...). Optional \u2014 sign up at https://user.blockrun.ai, pay by card, and calls bill your account credit instead of a wallet. Takes precedence over walletKey."
|
|
49
|
+
},
|
|
46
50
|
"walletKey": {
|
|
47
51
|
"type": "string",
|
|
48
52
|
"description": "EVM wallet private key (0x...). Optional \u2014 auto-generated if not set."
|
|
@@ -54,6 +58,11 @@
|
|
|
54
58
|
}
|
|
55
59
|
},
|
|
56
60
|
"uiHints": {
|
|
61
|
+
"apiKey": {
|
|
62
|
+
"label": "BlockRun API Key",
|
|
63
|
+
"sensitive": true,
|
|
64
|
+
"placeholder": "brk_live_... (optional \u2014 pay by card at user.blockrun.ai)"
|
|
65
|
+
},
|
|
57
66
|
"walletKey": {
|
|
58
67
|
"label": "Wallet Private Key",
|
|
59
68
|
"sensitive": true,
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@blockrun/clawrouter",
|
|
3
|
-
"version": "0.12.
|
|
4
|
-
"description": "Smart LLM router — save 84% on inference costs. 76 models (7 free)
|
|
3
|
+
"version": "0.12.268",
|
|
4
|
+
"description": "Smart LLM router — save 84% on inference costs. 76 models (7 free). Pay by credit card (API key) or USDC (x402 wallet).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
@@ -71,6 +71,7 @@
|
|
|
71
71
|
"blockrun",
|
|
72
72
|
"x402",
|
|
73
73
|
"usdc",
|
|
74
|
+
"api-key",
|
|
74
75
|
"cost-optimization",
|
|
75
76
|
"openai",
|
|
76
77
|
"anthropic",
|