agent402-openclaw 0.2.0 → 0.3.0

package/README.md

@@ -11,15 +11,24 @@ Guide: https://agent402.tools/guides/openclaw-model-provider
 
 ```bash
 openclaw plugins install agent402-openclaw
-AGENT402_CREDITS_KEY=a402_... agent402-openclaw setup --write   # key by env (or `--credits-key -` on stdin); buy one by card at https://agent402.tools/credits
+AGENT402_CREDITS_KEY=a402_... npx agent402-openclaw setup --write   # key by env (or `--credits-key -` on stdin); buy one by card at https://agent402.tools/credits
 openclaw gateway restart
 ```
 
-`setup` stores the key under `~/.openclaw/agent402/credits.key` (0600) and prints
-the `openclaw.json` block; add `--write` to merge it in (`agent402/auto` becomes
-the primary model). The plugin starts a loopback proxy (`127.0.0.1:8412`) that
+(`openclaw plugins install` copies the plugin into `~/.openclaw/extensions` and
+does not link its CLI, hence `npx`.) `setup` stores the key under
+`~/.openclaw/agent402/credits.key` (0600) and prints the `openclaw.json` block;
+add `--write` to merge it in. The primary model it writes is the cheapest
+metered model that can hold OpenClaw's own prompt: OpenClaw sends roughly 70k
+characters of system prompt and tool schemas before your first word, and the
+routed `auto` tier caps input at 16k, so `auto` stays listed for short one-off
+prompts but is never made primary (OpenClaw would refuse every turn as a
+context overflow). The plugin starts a loopback proxy (`127.0.0.1:8412`) that
 pays Agent402 and forwards; OpenClaw only ever sees a local OpenAI-compatible URL.
 
+Tested in CI against a real `openclaw@latest` install: plugin install, setup,
+model listing, gateway boot and one agent turn (`test-real-install.js`).
+
 No OpenClaw? `agent402-openclaw proxy` runs the proxy alone; point any OpenAI
 client at `http://127.0.0.1:8412/v1` with model `auto`.
 
@@ -33,6 +42,18 @@ export AGENT402_WALLET_KEY=0x...     # an EVM key holding USDC on Base
 With no credits key present the proxy signs an x402 payment per call from that
 wallet. The key never leaves the machine.
 
+Two ways the wallet can pay a metered call:
+
+- **exact** (default): the 402 quotes the call from its body (input + your
+  `max_tokens` at the model's list price, x1.15) and the wallet pays that quote.
+- **upto, actual usage**: run `agent402-openclaw permit2-approve` once (one USDC
+  approval transaction on Base; the wallet needs a little ETH for gas). From
+  then on the proxy authorizes the quote as a CEILING and the gateway settles
+  what the call actually cost x1.15, so a short answer costs a fraction of the
+  quote. `agent402-openclaw doctor` says which mode the wallet is in.
+
+Card / credits buyers already pay actual usage on metered calls.
+
 ## Models and pricing
 
 `auto` (routed per prompt, flat $0.01/call) plus every id from
@@ -53,8 +74,9 @@ the key.
 
 ## Commands
 
-- `agent402-openclaw setup [--credits-key K | --credits-key - (stdin) | AGENT402_CREDITS_KEY env] [--write] [--port N]`
+- `agent402-openclaw setup [--credits-key K | --credits-key - (stdin) | AGENT402_CREDITS_KEY env] [--write] [--port N] [--flat]`
 - `agent402-openclaw proxy [--port N] [--upstream URL]`
 - `agent402-openclaw doctor`
+- `agent402-openclaw permit2-approve [--rpc URL]` (one-time USDC approval so the wallet pays actual usage over upto)
 
 Zero dependencies. MIT. Maintained by Havok Holdings LLC.

package/cli.js

@@ -7,9 +7,9 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, statSync
 import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { STATE_DIR, CREDITS_KEY_FILE, resolveCreditsKey, resolvePayFetch } from "./index.js";
+import { STATE_DIR, CREDITS_KEY_FILE, resolveCreditsKey, resolvePayFetch, USDC_BASE, DEFAULT_BASE_RPC, uptoReady } from "./index.js";
 import { startProxy, loadRoutes, DEFAULT_UPSTREAM } from "./proxy.js";
-import { providerModelsConfig, stripTrailingSlashes } from "./models.js";
+import { providerModelsConfig, stripTrailingSlashes, defaultPrimary, AUTO_ID, OPENCLAW_MIN_INPUT_CHARS } from "./models.js";
 import { DEFAULT_PORT, PROVIDER_ID } from "./provider.js";
 
 const args = process.argv.slice(2);
@@ -20,24 +20,32 @@ const out = (s) => process.stdout.write(s + "\n");
 
 /** The provider block for openclaw.json (JSON, so it can be merged; OpenClaw reads JSON5 which is a superset). */
 export function configBlock({ port = DEFAULT_PORT, routes }) {
+  const primary = defaultPrimary(routes);
   return {
-    agents: { defaults: { model: { primary: `${PROVIDER_ID}/auto` } } },
+    agents: { defaults: { model: { primary: `${PROVIDER_ID}/${primary ? primary.id : AUTO_ID}` } } },
     models: { providers: { [PROVIDER_ID]: { ...providerModelsConfig(`http://127.0.0.1:${port}`, routes), timeoutSeconds: 120 } } },
   };
 }
 
-function mergeInto(target, block) {
+function mergeInto(target, block, { port = DEFAULT_PORT } = {}) {
   const t = target && typeof target === "object" ? target : {};
   t.agents = t.agents || {}; t.agents.defaults = t.agents.defaults || {};
   t.agents.defaults.model = { ...(t.agents.defaults.model || {}), primary: block.agents.defaults.model.primary };
   t.models = t.models || {}; t.models.providers = t.models.providers || {};
   t.models.providers[PROVIDER_ID] = block.models.providers[PROVIDER_ID];
+  // The plugin service reads ITS port from plugins.entries.<id>.config, not from
+  // the provider baseUrl - a --port that only moved the baseUrl left the proxy
+  // on 8412 and OpenClaw dialing a port nobody listened on (real-install test).
+  if (port !== DEFAULT_PORT) {
+    t.plugins = t.plugins || {}; t.plugins.entries = t.plugins.entries || {};
+    t.plugins.entries[PROVIDER_ID] = { ...(t.plugins.entries[PROVIDER_ID] || {}), config: { ...(t.plugins.entries[PROVIDER_ID]?.config || {}), port } };
+  }
   return t;
 }
 
 async function main() {
   if (cmd === "help" || has("--help")) {
-    out("agent402-openclaw setup [--credits-key a402_...|-] [--write] [--flat] | proxy [--port N] [--upstream URL] [--flat] | doctor");
+    out("agent402-openclaw setup [--credits-key a402_...|-] [--write] [--flat] | proxy [--port N] [--upstream URL] [--flat] | doctor | permit2-approve [--rpc URL]");
     return 0;
   }
   const upstream = stripTrailingSlashes(opt("--upstream") || process.env.AGENT402_UPSTREAM || DEFAULT_UPSTREAM);
@@ -64,6 +72,10 @@ async function main() {
     let routes;
     try { routes = await loadRoutes(upstream, fetch, { pricing }); } catch (e) { console.error(`could not read ${upstream}/v1/models: ${e?.message || e}`); return 2; }
     const block = configBlock({ port, routes });
+    const primary = block.agents.defaults.model.primary;
+    if (primary === `${PROVIDER_ID}/${AUTO_ID}`) {
+      console.error(`WARNING: no model in this catalog (${pricing} pricing) accepts the ~${Math.round(OPENCLAW_MIN_INPUT_CHARS / 1000)}k chars OpenClaw sends before your first word; primary falls back to ${primary}, which will answer "Context overflow" on every turn. Rerun without --flat to use the metered route.`);
+    }
     const cfgPath = join(process.env.AGENT402_OPENCLAW_HOME || join(homedir(), ".openclaw"), "openclaw.json");
     if (has("--write")) {
       let existing = {};
@@ -77,10 +89,10 @@ async function main() {
       let mode = 0o600;
       try { if (existsSync(cfgPath)) mode = statSync(cfgPath).mode & 0o777; } catch { /* keep 0600 */ }
       const tmp = `${cfgPath}.${process.pid}.tmp`;
-      writeFileSync(tmp, JSON.stringify(mergeInto(existing, block), null, 2) + "\n", { mode });
+      writeFileSync(tmp, JSON.stringify(mergeInto(existing, block, { port }), null, 2) + "\n", { mode });
       try { chmodSync(tmp, mode); } catch { /* best effort */ }
       renameSync(tmp, cfgPath);
-      out(`wrote provider "${PROVIDER_ID}" + primary model ${PROVIDER_ID}/auto into ${cfgPath}; run: openclaw gateway restart`);
+      out(`wrote provider "${PROVIDER_ID}" + primary model ${primary} into ${cfgPath}; run: openclaw gateway restart`);
     } else {
       out(`add to ${cfgPath} (or rerun with --write):`);
       out(JSON.stringify(block, null, 2));
@@ -96,11 +108,42 @@ async function main() {
     await new Promise(() => {}); // run until killed
   }
 
+  // One-time USDC -> Permit2 approval on Base so the wallet can pay ACTUAL
+  // usage over `upto` instead of the per-request quote over `exact`.
+  if (cmd === "permit2-approve") {
+    const pk = (process.env.AGENT402_WALLET_KEY || "").trim();
+    if (!/^0x[0-9a-fA-F]{64}$/.test(pk)) { console.error("AGENT402_WALLET_KEY (0x + 64 hex) is required"); return 2; }
+    try {
+      const [{ createPermit2ApprovalTx, getPermit2AllowanceReadParams }, { createWalletClient, createPublicClient, http }, { privateKeyToAccount }, { base }] = await Promise.all([import("@x402/evm/upto/client"), import("viem"), import("viem/accounts"), import("viem/chains")]);
+      const account = privateKeyToAccount(pk);
+      const rpc = (opt("--rpc") || process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim();
+      const pub = createPublicClient({ chain: base, transport: http(rpc) });
+      const read = () => pub.readContract(getPermit2AllowanceReadParams({ tokenAddress: USDC_BASE, ownerAddress: account.address }));
+      if (uptoReady(await read())) { out(`already approved: ${account.address} has a Permit2 allowance on USDC (Base); the proxy pays actual usage (upto)`); return 0; }
+      const tx = createPermit2ApprovalTx(USDC_BASE);
+      const wallet = createWalletClient({ account, chain: base, transport: http(rpc) });
+      const hash = await wallet.sendTransaction({ to: tx.to, data: tx.data });
+      out(`approval sent: ${hash} (waiting for confirmation)`);
+      await pub.waitForTransactionReceipt({ hash, timeout: 120_000 });
+      out(uptoReady(await read()) ? `approved: ${account.address} can now pay actual usage over upto. Restart the gateway.` : "transaction confirmed but the allowance still reads low - check the wallet on basescan");
+      return 0;
+    } catch (e) { console.error(`permit2-approve failed: ${String(e?.message || e).slice(0, 300)}`); return 1; }
+  }
+
   if (cmd === "doctor") {
     const key = resolveCreditsKey();
     out(`upstream: ${upstream}`);
     out(`credits key: ${key ? `present (${key.slice(0, 8)}…)` : "none"}`);
     out(`wallet key: ${/^0x[0-9a-fA-F]{64}$/.test(process.env.AGENT402_WALLET_KEY || "") ? "present" : "none"}`);
+    if (/^0x[0-9a-fA-F]{64}$/.test(process.env.AGENT402_WALLET_KEY || "")) {
+      try {
+        const [{ getPermit2AllowanceReadParams }, { createPublicClient, http }, { privateKeyToAccount }, { base }] = await Promise.all([import("@x402/evm/upto/client"), import("viem"), import("viem/accounts"), import("viem/chains")]);
+        const account = privateKeyToAccount(process.env.AGENT402_WALLET_KEY.trim());
+        const pub = createPublicClient({ chain: base, transport: http((process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim()) });
+        const allowance = await pub.readContract(getPermit2AllowanceReadParams({ tokenAddress: USDC_BASE, ownerAddress: account.address }));
+        out(`wallet ${account.address}: ${uptoReady(allowance) ? "pays actual usage (upto; Permit2 approved)" : "pays the per-request quote (exact) - run permit2-approve once to pay actual usage"}`);
+      } catch (e) { out(`wallet: allowance unreadable (${String(e?.message || e).slice(0, 80)})`); }
+    }
     try { const r = await loadRoutes(upstream, fetch, { pricing }); out(`gateway: ok, ${r.size} models (${pricing} pricing: ${[...r.values()].filter((x) => x.metered).length} metered)`); } catch (e) { out(`gateway: unreachable (${e?.message || e})`); return 1; }
     if (key) {
       try {

package/index.js

@@ -22,18 +22,55 @@ export function resolveCreditsKey(pluginConfig = {}) {
   return null;
 }
 
-/** Optional x402 wallet payment: only when the peer deps are installed and a key is present. */
+// x402 wallet payment - optional (peer deps) and, when the wallet has a
+// Permit2 allowance, METERED: the `upto` scheme authorizes a CEILING (the
+// per-request quote) and the gateway settles actual usage x 1.15, the way a
+// per-token router bills. Without the allowance it pays `exact` (the quote).
+export const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const BASE_CAIP2 = "eip155:8453";
+export const DEFAULT_BASE_RPC = "https://mainnet.base.org";
+// Permit2 approvals are max-uint by convention; anything this large is "approved".
+export const PERMIT2_READY_MIN = 10n ** 12n; // 1,000,000 USDC (6 decimals): a real approval, not dust
+
+/** Which 402 accept to pay: upto on Base when the client can (settle-actual),
+ *  else exact on Base, else the first the client supports. Pure. */
+export function selectAccept(accepts, { preferUpto = true } = {}) {
+  const list = Array.isArray(accepts) ? accepts : [];
+  if (preferUpto) { const u = list.find((a) => a?.scheme === "upto" && a?.network === BASE_CAIP2); if (u) return u; }
+  return list.find((a) => a?.scheme === "exact" && a?.network === BASE_CAIP2) || list[0];
+}
+export const uptoReady = (allowance) => { try { return BigInt(allowance ?? 0) >= PERMIT2_READY_MIN; } catch { return false; } };
+
 export async function resolvePayFetch(pluginConfig = {}, log = () => {}) {
   const pk = (pluginConfig.walletKey || process.env.AGENT402_WALLET_KEY || "").trim();
   if (!/^0x[0-9a-fA-F]{64}$/.test(pk)) return null;
   try {
-    const [{ wrapFetchWithPayment }, { privateKeyToAccount }] = await Promise.all([import("@x402/fetch"), import("viem/accounts")]);
-    const { toClientEvmSigner } = await import("@x402/evm");
-    const { registerExactEvmScheme } = await import("@x402/evm/exact/client");
-    const { x402Client } = await import("@x402/fetch");
-    const client = new x402Client();
-    registerExactEvmScheme(client, { signer: toClientEvmSigner(privateKeyToAccount(pk)) });
-    return wrapFetchWithPayment(fetch, client);
+    const [{ wrapFetchWithPayment, x402Client }, { privateKeyToAccount }, { toClientEvmSigner }, { registerExactEvmScheme }] = await Promise.all([
+      import("@x402/fetch"), import("viem/accounts"), import("@x402/evm"), import("@x402/evm/exact/client"),
+    ]);
+    const account = privateKeyToAccount(pk);
+    const signer = toClientEvmSigner(account);
+    // Upto needs a Permit2 allowance on USDC (one approval transaction, ever).
+    let upto = false;
+    try {
+      const [{ UptoEvmScheme, getPermit2AllowanceReadParams }, { createPublicClient, http }, { base }] = await Promise.all([import("@x402/evm/upto/client"), import("viem"), import("viem/chains")]);
+      const pub = createPublicClient({ chain: base, transport: http((pluginConfig.baseRpc || process.env.AGENT402_BASE_RPC || DEFAULT_BASE_RPC).trim()) });
+      const allowance = await pub.readContract(getPermit2AllowanceReadParams({ tokenAddress: USDC_BASE, ownerAddress: account.address }));
+      upto = uptoReady(allowance);
+      const client = new x402Client((v, accepts) => selectAccept(accepts, { preferUpto: upto }));
+      registerExactEvmScheme(client, { signer });
+      if (upto) client.register(BASE_CAIP2, new UptoEvmScheme(signer));
+      log(upto
+        ? `[agent402-openclaw] x402 wallet ${account.address}: paying actual usage (upto, Permit2 allowance present) on Base; exact elsewhere`
+        : `[agent402-openclaw] x402 wallet ${account.address}: paying the per-request quote (exact). To pay actual usage instead, run \`agent402-openclaw permit2-approve\` once (one USDC approval transaction on Base; needs a little ETH for gas)`);
+      return wrapFetchWithPayment(fetch, client);
+    } catch (e) {
+      // The allowance read or the upto scheme failed: exact still works.
+      log(`[agent402-openclaw] upto unavailable (${String(e?.message || e).slice(0, 120)}) - paying exact`);
+      const client = new x402Client((v, accepts) => selectAccept(accepts, { preferUpto: false }));
+      registerExactEvmScheme(client, { signer });
+      return wrapFetchWithPayment(fetch, client);
+    }
   } catch (e) {
     log(`[agent402-openclaw] x402 wallet payment unavailable (${e?.message || e}); install @x402/fetch @x402/evm viem, or use a credits key`);
     return null;

package/models.js

@@ -8,6 +8,23 @@
 
 export const AUTO_ID = "auto";
 
+/** The metered route's own caps (llm-gateway-kit TIERS["v1-chat-metered"]),
+ *  used when the catalog entry does not carry `meteredMaxInputChars` /
+ *  `meteredMaxTokens` (gateways older than 2026-08-26). A metered call is
+ *  validated against the METERED tier's limits, never the model's flat home
+ *  tier - so a nano model that takes 12k chars flat takes 200k chars metered. */
+export const METERED_MAX_INPUT_CHARS = 200_000;
+export const METERED_MAX_TOKENS = 8192;
+
+/** What a model must accept to be OpenClaw's primary. Measured on OpenClaw
+ *  2026.7.1 with the stock agent: ~33k chars of system prompt plus ~37k chars
+ *  of tool schemas BEFORE the user's first word, and OpenClaw's own precheck
+ *  refuses the turn ("Context overflow") when that exceeds the model's
+ *  contextWindow. The routed `auto` tier caps input at 16k chars, so a primary
+ *  of `agent402/auto` never completes a single turn - found by the real-install
+ *  test, invisible to every stub. */
+export const OPENCLAW_MIN_INPUT_CHARS = 80_000;
+
 /** Linear trailing-slash strip (a regex like /\/+$/ is polynomial on long runs of "/"). */
 export function stripTrailingSlashes(s) {
   let str = String(s ?? ""); let end = str.length;
@@ -40,8 +57,8 @@ export function routesFromCatalog(catalog, { pricing = "metered" } = {}) {
       tier: useMetered ? "v1-chat-metered" : (x.tier || null),
       priceUsd: useMetered ? (Number(x.meteredFromUsd) || x.priceUsd) : x.priceUsd,
       metered: useMetered,
-      maxTokens: Number(x.maxTokens) || 1024,
-      maxInputChars: Number(x.maxInputChars) || 32_000,
+      maxTokens: useMetered ? (Number(x.meteredMaxTokens) || METERED_MAX_TOKENS) : (Number(x.maxTokens) || 1024),
+      maxInputChars: useMetered ? (Number(x.meteredMaxInputChars) || METERED_MAX_INPUT_CHARS) : (Number(x.maxInputChars) || 32_000),
       stealth: !!x.stealth,
     });
   }
@@ -58,6 +75,23 @@ export function routesFromCatalog(catalog, { pricing = "metered" } = {}) {
   return routes;
 }
 
+/** Preferred primaries, in order: capable tool-callers that are cheap when
+ *  metered. Only consulted among routes that can hold OpenClaw's prompt. */
+const PRIMARY_PREFERENCE = ["anthropic/claude-haiku-4.5", "openai/gpt-4.1-mini", "google/gemini-2.5-flash", "openai/gpt-4o-mini"];
+
+/** The route OpenClaw should make its primary model: the first preferred id
+ *  that fits OPENCLAW_MIN_INPUT_CHARS, else the cheapest fitting one, else
+ *  null (nothing in this catalog can hold OpenClaw's prompt - the caller says
+ *  so instead of writing a primary that fails every turn). `auto` is never
+ *  chosen: its input cap is the routed tier's. */
+export function defaultPrimary(routes, { minInputChars = OPENCLAW_MIN_INPUT_CHARS } = {}) {
+  const fits = [...routes.values()].filter((r) => r.id !== AUTO_ID && !r.stealth && r.maxInputChars >= minInputChars);
+  if (!fits.length) return null;
+  for (const id of PRIMARY_PREFERENCE) { const r = fits.find((x) => x.id === id); if (r) return r; }
+  fits.sort((a, b) => a.priceUsd - b.priceUsd || a.id.localeCompare(b.id));
+  return fits[0];
+}
+
 const priceLabel = (usd) => (usd < 0.01 ? `$${usd.toFixed(3)}` : `$${usd.toFixed(2)}`);
 
 /** OpenClaw `models[]` entries for a provider block. `auto` first. */

package/openclaw.plugin.json

@@ -6,5 +6,48 @@
     "onStartup": true
   },
   "enabledByDefault": true,
-  "providers": ["agent402"]
+  "providers": [
+    "agent402"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "creditsKey": {
+        "type": "string",
+        "description": "Agent402 prepaid credits key (a402_...). Precedence: this, then AGENT402_CREDITS_KEY, then ~/.openclaw/agent402/credits.key."
+      },
+      "walletKey": {
+        "type": "string",
+        "description": "Optional EVM private key for x402 USDC payment (needs @x402/fetch + @x402/evm + viem installed)."
+      },
+      "port": {
+        "type": "number",
+        "description": "Loopback proxy port (default 8412)."
+      },
+      "upstream": {
+        "type": "string",
+        "description": "Agent402 gateway base URL (default https://agent402.tools)."
+      },
+      "pricing": {
+        "type": "string",
+        "enum": [
+          "metered",
+          "flat"
+        ],
+        "description": "metered (default): explicit models pay a per-request quote; flat: every model on its flat tier."
+      }
+    }
+  },
+  "uiHints": {
+    "creditsKey": {
+      "label": "Credits key",
+      "help": "Buy by card at https://agent402.tools/credits",
+      "sensitive": true
+    },
+    "walletKey": {
+      "label": "Wallet key",
+      "sensitive": true
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-openclaw",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenClaw model provider for Agent402: auto-routed and explicit LLM models at a flat per-call price, paid by card (prepaid credits key) or in USDC over x402 through a local proxy. Zero dependencies; x402 wallet payment is an optional peer.",
   "type": "module",
   "main": "index.js",