agent402-openclaw 0.2.0 → 0.2.1

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`.
 
@@ -53,7 +62,7 @@ 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`
 

package/cli.js

@@ -9,7 +9,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { STATE_DIR, CREDITS_KEY_FILE, resolveCreditsKey, resolvePayFetch } 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,18 +20,26 @@ 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;
 }
 
@@ -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));

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.2.1",
   "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",