@drakon-systems/multi-clawd 1.0.0

package/openclaw.plugin.json

@@ -0,0 +1,134 @@
+{
+  "id": "multi-clawd",
+  "name": "multi-clawd",
+  "description": "Register additional Claude Code logins (Max/Pro accounts) as first-class OpenClaw CLI backends for cross-account failover, keeping the full skills/MCP harness on every account.",
+  "cliBackends": ["claw1", "claw2", "clawd"],
+  "providers": ["claw1", "claw2", "clawd"],
+  "modelCatalog": {
+    "runtimeAugment": true
+  },
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "pool": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Pooled backend: one backend id fronting several accounts. Every launch runs on the first pooled account that is not nearly maxed out (from each account's rate_limit_event health state), so a near-limit home account hands over BEFORE it hard-fails. Route your chain at <pool.id>/<model> to get proactive same-model account failover.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Backend id / provider prefix for the pool. Default \"clawd\"."
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-friendly label shown in status/catalog."
+          },
+          "accounts": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Account ids (from accounts[]) in preference order; the first is the home account and reclaims the pool when its usage window resets."
+          },
+          "utilizationThreshold": {
+            "type": "number",
+            "description": "Hand over when any rate-limit window's utilization reaches this fraction. Default 0.85."
+          },
+          "staleAfterMs": {
+            "type": "number",
+            "description": "Ignore health data older than this. Default 21600000 (6h)."
+          },
+          "minDwellMs": {
+            "type": "number",
+            "description": "After rotating away from home, stay on the rotated-to account at least this long before returning home (anti-flap hysteresis; health always overrides). Default 600000 (10min)."
+          },
+          "degrade": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Tier-aware degradation (v0.3.5): when EVERY pooled account is exhausted, launch on the requested model's same-provider fallback tier instead of hard-failing to the next provider. While any account can still serve the requested tier, rotation always wins. Also enables single-account pools (a pool of one account + a ladder replaces a bespoke tier-switch watcher).",
+            "properties": {
+              "ladder": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Same-provider models to step down to, best first (e.g. [\"claude-opus-4-8\"]). Requests already at/below the ladder never degrade further."
+              },
+              "pins": {
+                "type": "array",
+                "description": "Never-degrade lanes: launches matching any pin keep their requested model and fail over via the chain instead (contractual model lanes).",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "agentDirIncludes": { "type": "string", "description": "Pin when the launching agent's dir contains this substring." },
+                    "workspaceDirIncludes": { "type": "string", "description": "Pin when the workspace dir contains this substring." }
+                  }
+                }
+              }
+            }
+          },
+          "models": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Extra model ids to expose on the pool backend."
+          },
+          "defaultModel": {
+            "type": "string",
+            "description": "Model id used for live probes. Defaults to claude-fable-5."
+          }
+        }
+      },
+      "accounts": {
+        "type": "array",
+        "description": "Additional Claude accounts to register as CLI backends. Each becomes a provider prefix usable in model refs and fallback chains, e.g. claw2/claude-fable-5.",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id"],
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Backend id / provider prefix, e.g. 'claw2'. Must be unique and not collide with the bundled 'claude-cli'."
+            },
+            "label": {
+              "type": "string",
+              "description": "Human-friendly label shown in status/catalog."
+            },
+            "native": {
+              "type": "boolean",
+              "description": "Use the machine's native Claude login (default config dir; OS keychain on macOS). Sets neither CLAUDE_CONFIG_DIR nor a token. Use this to include the main account in the rotation pool."
+            },
+            "configDir": {
+              "type": "string",
+              "description": "Isolated CLAUDE_CONFIG_DIR for this login (keeps its sessions separate from the native login and other accounts)."
+            },
+            "oauthTokenFile": {
+              "type": "string",
+              "description": "Path to a file (0600) containing this account's Claude Code setup-token. Read at launch and passed as CLAUDE_CODE_OAUTH_TOKEN. Mutually exclusive with oauthTokenRef."
+            },
+            "oauthTokenRef": {
+              "type": "object",
+              "description": "Secret reference resolving to this account's Claude Code setup-token via the gateway's configured secret providers — same shape as every other secret in openclaw.json, e.g. {\"source\":\"exec\",\"provider\":\"onepassword\",\"id\":\"op://Vault/Item/field\"}. Preferred over oauthTokenFile (no plaintext on disk). Resolution failures degrade the account (auth fails, chain steps) rather than crashing the launch.",
+              "additionalProperties": true,
+              "properties": {
+                "source": { "type": "string", "description": "Secret source kind: env | file | exec." },
+                "provider": { "type": "string", "description": "Configured secret provider name, e.g. \"onepassword\"." },
+                "id": { "type": "string", "description": "Provider-scoped secret id, e.g. an op:// reference." }
+              }
+            },
+            "models": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Extra model ids to expose for this account beyond the mirrored claude-cli catalog (e.g. a brand-new model OpenClaw doesn't list yet). Unknown modern claude-* ids also resolve on demand without being listed here."
+            },
+            "defaultModel": {
+              "type": "string",
+              "description": "Model id used for live probes (openclaw models status). Defaults to claude-fable-5."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@drakon-systems/multi-clawd",
+  "version": "1.0.0",
+  "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Drakon Systems Ltd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Drakon-Systems-Ltd/multi-clawd.git"
+  },
+  "keywords": [
+    "openclaw",
+    "claude",
+    "claude-code",
+    "cli-backend",
+    "failover",
+    "multi-account",
+    "anthropic",
+    "plugin"
+  ],
+  "openclaw": {
+    "build": {
+      "openclawVersion": "2026.6.11"
+    },
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    }
+  },
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "npm run build",
+    "doctor": "node scripts/doctor.mjs",
+    "setup": "node scripts/setup.mjs"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.6"
+  },
+  "devDependencies": {
+    "openclaw": "2026.7.1",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.10"
+  }
+}

package/scripts/doctor.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+/**
+ * multi-clawd doctor — one command that says whether this box is actually
+ * ready (per the v0.3 spec). Checks, without ever printing secret values:
+ *
+ *   1. plugin install + manifest/config key agreement (the --force trap)
+ *   2. compiled-artifact freshness (stale dist detection)
+ *   3. claude CLI availability + PATH sanity
+ *   4. per-account credential-source health
+ *   5. per-account rate-limit telemetry (state files, age, windows)
+ *   6. pool configuration + sticky state
+ *   7. effective chain — Claude tiers must route through the clawd pool
+ *   8. eviction watchdog presence (launchd/systemd)
+ *
+ * Flags:
+ *   --preflight   print the exact config keys to strip before a --force
+ *                 install against an older installed manifest
+ *   --probe       spend one cheap turn proving the pool answers end-to-end
+ *
+ * Exit code: 0 all good, 1 any ❌.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOME = homedir();
+const EXT_DIR = join(HOME, ".openclaw", "extensions", "multi-clawd");
+const CONFIG_PATH = join(HOME, ".openclaw", "openclaw.json");
+const STATE_DIR = join(HOME, ".openclaw", "state", "multi-clawd");
+const REPO_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const args = new Set(process.argv.slice(2));
+let failures = 0;
+const ok = (msg) => console.log(`  ✅ ${msg}`);
+const warn = (msg) => console.log(`  ⚠️  ${msg}`);
+const note = (msg) => console.log(`  ℹ️  ${msg}`);
+const bad = (msg) => {
+  failures++;
+  console.log(`  ❌ ${msg}`);
+};
+
+function expandHome(p) {
+  if (p === "~") return HOME;
+  if (p?.startsWith("~/")) return join(HOME, p.slice(2));
+  return p;
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function newestMtime(dir, exts) {
+  let newest = 0;
+  let newestFile = "";
+  try {
+    for (const f of readdirSync(dir)) {
+      if (!exts.some((e) => f.endsWith(e))) continue;
+      const m = statSync(join(dir, f)).mtimeMs;
+      if (m > newest) {
+        newest = m;
+        newestFile = f;
+      }
+    }
+  } catch {
+    /* missing dir */
+  }
+  return { newest, newestFile };
+}
+
+console.log("multi-clawd doctor\n");
+
+// ── 1. install + manifest/config agreement ─────────────────────────────────
+console.log("install & config");
+const manifest = readJson(join(EXT_DIR, "openclaw.plugin.json"));
+const config = readJson(CONFIG_PATH);
+const entry = config?.plugins?.entries?.["multi-clawd"];
+const pluginConfig = entry?.config ?? {};
+if (!manifest) bad(`no installed manifest at ${EXT_DIR}`);
+else ok(`installed at ${EXT_DIR}`);
+if (!entry) bad("no plugins.entries[\"multi-clawd\"] in openclaw.json");
+else if (entry.enabled !== true) bad("plugin entry present but not enabled");
+else ok("plugin entry enabled");
+const allow = config?.plugins?.allow;
+if (Array.isArray(allow) && !allow.includes("multi-clawd")) {
+  bad('plugins.allow exists but does not include "multi-clawd"');
+} else ok("plugins.allow OK");
+
+const unknownKeys = [];
+if (manifest && pluginConfig) {
+  const schemaProps = manifest.configSchema?.properties ?? {};
+  for (const key of Object.keys(pluginConfig)) {
+    if (!schemaProps[key]) unknownKeys.push(key);
+  }
+  const accountProps = schemaProps.accounts?.items?.properties ?? {};
+  for (const [i, account] of (pluginConfig.accounts ?? []).entries()) {
+    for (const key of Object.keys(account)) {
+      if (!accountProps[key]) unknownKeys.push(`accounts[${i}].${key}`);
+    }
+  }
+  const poolProps = schemaProps.pool?.properties ?? {};
+  for (const key of Object.keys(pluginConfig.pool ?? {})) {
+    if (!poolProps[key]) unknownKeys.push(`pool.${key}`);
+  }
+}
+if (unknownKeys.length > 0) {
+  bad(
+    `config keys the INSTALLED manifest does not know: ${unknownKeys.join(", ")} — a --force install will refuse. Strip them, install, re-add (SETUP-AGENT.md §6).`,
+  );
+} else ok("config keys all known to installed manifest");
+if (args.has("--preflight")) {
+  console.log(
+    unknownKeys.length > 0
+      ? `\npreflight: strip these keys first → ${unknownKeys.join(", ")}\n`
+      : "\npreflight: config is manifest-clean; --force install is safe as-is\n",
+  );
+}
+
+// ── 2. dist freshness ───────────────────────────────────────────────────────
+console.log("build artifacts");
+// Tolerance matters: `openclaw plugins install` copies dist/ before src/ with
+// fresh mtimes, so the installed copy's src is always seconds "newer". A
+// genuinely stale dist (pulled src, forgot to build) lags by minutes-to-days.
+const STALE_TOLERANCE_MS = 120_000;
+for (const [label, dir] of [["installed", EXT_DIR], ["checkout", REPO_DIR]]) {
+  const src = newestMtime(join(dir, "src"), [".ts"]);
+  const dist = newestMtime(join(dir, "dist"), [".js"]);
+  if (src.newest === 0) continue;
+  if (dist.newest === 0) bad(`${label}: no dist/ — run npm run build`);
+  else if (src.newest > dist.newest + STALE_TOLERANCE_MS)
+    bad(`${label}: dist is STALE (src ${src.newestFile} newer than dist) — run npm run build`);
+  else ok(`${label}: dist fresh`);
+}
+
+// ── 3. claude CLI + PATH ────────────────────────────────────────────────────
+console.log("claude CLI");
+try {
+  const v = execFileSync("claude", ["--version"], { encoding: "utf8", timeout: 15000 }).trim();
+  ok(`claude on PATH (${v.split("\n")[0]})`);
+} catch {
+  bad("claude CLI not found on PATH");
+}
+
+// ── 4. account credentials (values never printed) ──────────────────────────
+console.log("account credentials");
+const { checkAccountCredential } = await import(join(EXT_DIR, "dist", "login-health.js")).catch(
+  () => import(join(REPO_DIR, "dist", "login-health.js")),
+);
+const io = {
+  readFile: (p) => readFileSync(expandHome(p), "utf8"),
+  keychainHasClaudeCredentials: () => {
+    try {
+      execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials"], {
+        stdio: "ignore",
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  platform: process.platform,
+};
+const accounts = pluginConfig.accounts ?? [];
+if (accounts.length === 0) warn("no accounts configured");
+for (const account of accounts) {
+  if (account.oauthTokenRef) {
+    warn(`${account.id}: oauthTokenRef — validated by the gateway's async probe, not doctor`);
+    continue;
+  }
+  const check = checkAccountCredential(account, io);
+  if (check.status === "ok") ok(`${account.id}: credential source looks alive`);
+  else if (check.status === "unknown") warn(`${account.id}: cannot verify (${check.reason ?? "no source"})`);
+  else bad(`${account.id}: ${check.reason}`);
+}
+
+// ── 5. telemetry state ──────────────────────────────────────────────────────
+console.log("rate-limit telemetry");
+for (const account of accounts) {
+  const state = readJson(join(STATE_DIR, `${account.id}.json`));
+  if (!state) {
+    warn(`${account.id}: no health state yet (fills after its first turn)`);
+    continue;
+  }
+  const ageMin = Math.round((Date.now() - (state.updatedAt ?? 0)) / 60000);
+  const windows = Object.entries(state.windows ?? {})
+    .map(([w, d]) => `${w}:${d.status}${typeof d.utilization === "number" ? `@${Math.round(d.utilization * 100)}%` : ""}`)
+    .join(" ");
+  ok(`${account.id}: ${windows || "no windows"} (${ageMin}m old)`);
+}
+
+// ── 6. pool ─────────────────────────────────────────────────────────────────
+console.log("pool");
+const pool = pluginConfig.pool;
+if (!pool) warn("no pool configured — direct backends only, no proactive rotation");
+else {
+  const members = (pool.accounts ?? []).filter((id) => accounts.some((a) => a.id === id));
+  if (members.length < 2) bad(`pool "${pool.id ?? "clawd"}" has ${members.length} valid member(s); needs ≥ 2`);
+  else ok(`pool "${pool.id ?? "clawd"}": ${members.join(" → ")}`);
+  const sticky = readJson(join(STATE_DIR, `pool-${pool.id ?? "clawd"}.sticky.json`));
+  if (sticky) warn(`pool is currently stuck to ${sticky.account} (since ${new Date(sticky.since).toISOString()})`);
+  else ok("no sticky — pool is on its home account");
+}
+
+// ── 7. effective chain (pool-bypass sweep — CASE 1 config + CASE 2 session) ──
+//
+// CASE 1: a STATIC, at-rest scan of openclaw.json. Every Claude model reference
+// under `agents` must route through the clawd pool; a Claude tier pinned to
+// `anthropic/…`, `claude-cli/…`, or a single `claw<N>/…` account silently
+// defeats cross-account failover — yet doctor used to still say READY (e.g.
+// a Claude fallback pinned to `anthropic/claude-fable-5`).
+//
+// CASE 2: a STATIC scan of session state. A persisted per-session `/model`
+// override (`~/.openclaw/agents/<agent>/sessions/sessions.json`) bypasses the
+// pool exactly like a config pin but lives outside openclaw.json — invisible to
+// case 1. Same off-pool predicate, same warn classes.
+//
+// Both emit warn(), never bad(): a box may *intentionally* pin one account or
+// one session, so neither may flip the exit code / READY.
+console.log("effective chain");
+if (!pool) {
+  // No clawd pool ⇒ nothing to bypass; skip the whole section (mirrors §6).
+} else {
+  const { auditEffectiveChain, auditSessionOverrides, maskSessionKey } = await import(
+    join(EXT_DIR, "dist", "chain-audit.js")
+  ).catch(() => import(join(REPO_DIR, "dist", "chain-audit.js")));
+  const poolId = pool.id ?? "clawd";
+  const verbose = process.env.DOCTOR_VERBOSE === "1" || process.argv.includes("--verbose");
+  // Session keys embed the operator's private channel id (e.g. a Telegram chat
+  // id). Mask the id tail by default so doctor output is safe to paste into
+  // issues/support threads; `--raw` restores full keys for local exact-match
+  // debugging. Only case-2 session surfaces carry a key; config surfaces don't.
+  const raw = process.env.DOCTOR_RAW === "1" || process.argv.includes("--raw");
+  const renderSurface = (surface) =>
+    raw ? surface : surface.replace(/^session (.+)$/, (_m, k) => `session ${maskSessionKey(k)}`);
+
+  // ── case 1: config-level refs ──────────────────────────────────────────────
+  const findings = auditEffectiveChain(config, poolId);
+  const warns = findings.filter((f) => f.severity === "warn");
+  const notes = findings.filter((f) => f.severity === "note");
+  for (const f of warns) warn(`${f.surface}: ${f.ref} ${f.reason}`);
+  // Allowlist entries are registered-but-not-live rungs: informational only,
+  // and there are typically many (every non-pool Claude id someone MAY ref).
+  // Collapse to one line so the section stays scannable; DOCTOR_VERBOSE lists
+  // them. A dead-noisy section trains people to skip it — the opposite of the
+  // point. (Live-tier bypasses above are always listed in full.)
+  if (notes.length > 0) {
+    if (verbose) {
+      for (const f of notes) {
+        note(`${f.surface}: ${f.ref} (allowlist entry, not a live tier) ${f.reason}`);
+      }
+    } else {
+      note(
+        `${notes.length} allowlist rung(s) name a non-pool Claude ref (registered, not a live tier) — run with --verbose to list`,
+      );
+    }
+  }
+  if (warns.length === 0) ok(`effective chain: all live Claude tiers route through the ${poolId} pool`);
+
+  // ── case 2: session-level /model overrides ─────────────────────────────────
+  // Enumerate agents/*/sessions/sessions.json. A store that is expected (its
+  // agent has a sessions/ dir) but absent/unparseable gets a LOUD skip — never
+  // a silent pass; a missed off-pool pin is worse than an extra line.
+  const AGENTS_DIR = join(HOME, ".openclaw", "agents");
+  const stores = [];
+  try {
+    for (const agent of readdirSync(AGENTS_DIR)) {
+      const sessionsDir = join(AGENTS_DIR, agent, "sessions");
+      if (!existsSync(sessionsDir)) continue; // not an agent-with-sessions
+      stores.push(join(sessionsDir, "sessions.json"));
+    }
+  } catch {
+    /* no agents dir at all */
+  }
+  if (stores.length === 0) {
+    note("session overrides: no agent session stores found (clean environment)");
+  } else {
+    let sessionWarns = 0;
+    let readable = 0;
+    for (const storePath of stores) {
+      const parsed = readJson(storePath);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        warn(`session-override check SKIPPED for ${storePath} (store unreadable)`);
+        continue;
+      }
+      readable++;
+      const sessionFindings = auditSessionOverrides(parsed, true);
+      for (const f of sessionFindings) {
+        warn(`${renderSurface(f.surface)}: ${f.ref} ${f.reason}`);
+        sessionWarns++;
+      }
+    }
+    if (readable > 0 && sessionWarns === 0) ok("session overrides: no off-pool /model pins");
+  }
+}
+
+// ── 8. watchdog ─────────────────────────────────────────────────────────────
+console.log("eviction watchdog");
+let watchdogFound = false;
+try {
+  const out = execFileSync("launchctl", ["list"], { encoding: "utf8" });
+  if (out.includes("multiclawd")) watchdogFound = true;
+} catch {
+  /* not macOS */
+}
+try {
+  const out = execFileSync("systemctl", ["--user", "list-timers", "--all"], { encoding: "utf8" });
+  if (out.includes("multi-clawd") || out.includes("multiclawd") || out.includes("eviction")) watchdogFound = true;
+} catch {
+  /* not systemd */
+}
+if (watchdogFound) ok("watchdog scheduled");
+else warn("no watchdog found (needed until openclaw#107596 ships — see README)");
+
+// ── 9. optional live probe ──────────────────────────────────────────────────
+if (args.has("--probe")) {
+  console.log("live probe (spends one turn)");
+  const ref = pool ? `${pool.id ?? "clawd"}/${pool.defaultModel ?? "claude-fable-5"}` : accounts[0] ? `${accounts[0].id}/claude-fable-5` : undefined;
+  if (!ref) bad("nothing to probe");
+  else {
+    try {
+      const out = execFileSync(
+        "openclaw",
+        ["agent", "--agent", "main", "--session-key", "agent:main:mc-doctor-probe", "--model", ref, "--json", "--message", "Reply with exactly this line and nothing else: MC_DOCTOR_OK. Do not use any tools."],
+        { encoding: "utf8", timeout: 180000 },
+      );
+      if (out.includes("MC_DOCTOR_OK")) ok(`${ref} answered end-to-end`);
+      else bad(`${ref} probe returned unexpected output`);
+    } catch (err) {
+      bad(`${ref} probe failed: ${String(err).slice(0, 200)}`);
+    }
+  }
+}
+
+console.log(failures === 0 ? "\ndoctor: READY 🦞" : `\ndoctor: ${failures} problem(s) found`);
+process.exit(failures === 0 ? 0 : 1);