oc-inspector 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,29 @@
 # oc-inspector
 
-Real-time API traffic inspector for [OpenClaw](https://openclaw.ai). Intercepts LLM provider requests (Anthropic, OpenAI, BytePlus, Ollama, and more), shows token usage, costs, and message flow in a live web dashboard.
+A debugging and monitoring tool for [OpenClaw](https://openclaw.ai) that helps you understand **where your tokens and money are going**.
+
+When working with LLM agents you often have no visibility into what's actually happening under the hood — how many tokens each request burns, which models cost the most, what system prompts look like, how tool calls are structured. `oc-inspector` sits between OpenClaw and your LLM providers as a transparent proxy, capturing every request and response in real time so you can see the full picture: token usage, costs, message flow, thinking blocks, tool calls — everything in a clear, human-readable format.
+
+Use it to:
+- **Debug** agent behavior by inspecting actual API requests and responses
+- **Find token leaks** — see which conversations, models, or providers consume the most
+- **Track costs** — per-request, per-model, per-day breakdowns with persistent history
+- **Understand** what OpenClaw sends to each provider (system prompts, tool definitions, context)
+
+> **⚠️ USE AT YOUR OWN RISK**
+>
+> This tool works by patching `openclaw.json` to route API traffic through a local proxy. While it includes safeguards (automatic config restore on stop/shutdown, backup files, double-enable protection), **always keep a manual backup of your `openclaw.json` before using the inspector**:
+>
+> ```bash
+> cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.manual-backup
+> ```
+>
+> If something goes wrong, restore it:
+>
+> ```bash
+> cp ~/.openclaw/openclaw.json.manual-backup ~/.openclaw/openclaw.json
+> openclaw gateway restart
+> ```
 
 ## Quick Start
 
@@ -8,7 +31,7 @@ Real-time API traffic inspector for [OpenClaw](https://openclaw.ai). Intercepts
 npx oc-inspector
 ```
 
-Opens the inspector proxy on `localhost:18800` with a live web dashboard.
+Starts the inspector daemon in background on `localhost:18800` with a live web dashboard.
 
 ---
 

package/bin/cli.mjs

@@ -38,6 +38,17 @@ import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const args = process.argv.slice(2);
 
+// ── ANSI escapes & column widths (must be before command routing) ──
+const E = {
+  R: "\x1b[0m", B: "\x1b[1m", D: "\x1b[90m",
+  RED: "\x1b[31m", GRN: "\x1b[32m", YEL: "\x1b[33m",
+  CYN: "\x1b[36m", ORG: "\x1b[38;5;208m",
+  BG: "\x1b[48;5;236m",
+  CLR: "\x1b[2J\x1b[H",
+  HIDE: "\x1b[?25l", SHOW: "\x1b[?25h",
+};
+const COL = { name: 24, bar: 20, tokens: 8, reqs: 7, cost: 10 };
+
 /** Inspector state directory for PID/log files. */
 const INSPECTOR_DIR = join(homedir(), ".openclaw", ".inspector-runtime");
 
@@ -59,6 +70,7 @@ function parseArgs(argv) {
     open: false,
     config: undefined,
     json: false,
+    live: false,
     days: 7,
     lines: 50,
     help: false,
@@ -67,7 +79,7 @@ function parseArgs(argv) {
     "start", "stop", "run", "restart",
     "enable", "disable", "status",
     "stats", "providers", "history", "pricing", "config",
-    "logs", "_serve",
+    "logs", "help", "_serve",
   ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -76,6 +88,7 @@ function parseArgs(argv) {
     if (arg === "--open") { opts.open = true; continue; }
     if (arg === "--config" && argv[i + 1]) { opts.config = argv[++i]; continue; }
     if (arg === "--json") { opts.json = true; continue; }
+    if (arg === "--live" || arg === "-w") { opts.live = true; continue; }
     if (arg === "--days" && argv[i + 1]) { opts.days = parseInt(argv[++i], 10); continue; }
     if (arg === "--lines" && argv[i + 1]) { opts.lines = parseInt(argv[++i], 10); continue; }
     if (arg === "--help" || arg === "-h") { opts.help = true; continue; }
@@ -117,6 +130,7 @@ if (opts.help) {
     --open            Auto-open the dashboard in a browser
     --config <path>   Custom path to openclaw.json
     --json            Output as JSON (for stats, status, providers, history)
+    --live, -w        Live auto-refreshing stats (for stats command)
     --days <number>   Number of days to show in history (default: 7)
     --lines <number>  Number of log lines to show (default: 50)
     --help, -h        Show this help message
@@ -128,7 +142,8 @@ if (opts.help) {
     npx oc-inspector restart           # Restart daemon
     npx oc-inspector enable            # Enable interception
     npx oc-inspector disable           # Disable interception
-    npx oc-inspector stats             # Show live token stats
+    npx oc-inspector stats             # Show token stats
+    npx oc-inspector stats --live      # Live auto-refreshing dashboard
     npx oc-inspector stats --json      # Stats as JSON
     npx oc-inspector history --days 30 # Last 30 days
     npx oc-inspector pricing           # Show pricing table
@@ -141,6 +156,15 @@ if (opts.help) {
 // Command routing
 // ═══════════════════════════════════════════════════════════════
 
+// help: show commands
+if (opts.command === "help") {
+  console.log("");
+  console.log("  \x1b[38;5;208m🦞 oc-inspector\x1b[0m — Real-time API traffic inspector for OpenClaw");
+  console.log("");
+  printCommandsHelp();
+  process.exit(0);
+}
+
 // Hidden: _serve is the actual foreground server (spawned by start)
 if (opts.command === "_serve") {
   await runServe(opts);
@@ -152,15 +176,16 @@ if (opts.command === "start") {
   process.exit(0);
 }
 
-// stop: kill daemon
+// stop: kill daemon + restore config
 if (opts.command === "stop") {
-  runDaemonStop();
+  console.log("");
+  await runDaemonStop(false, opts);
   process.exit(0);
 }
 
 // restart: stop + start
 if (opts.command === "restart") {
-  runDaemonStop(/* silent */ true);
+  await runDaemonStop(/* silent */ true, opts);
   await new Promise((r) => setTimeout(r, 800));
   await runDaemonStart(opts);
   process.exit(0);
@@ -212,8 +237,7 @@ async function runDaemonStart(opts) {
     console.log(`  \x1b[33m⚠\x1b[0m  Already running (PID ${running.pid})`);
     console.log(`  \x1b[32m✓\x1b[0m Dashboard:  http://127.0.0.1:${opts.port}`);
     console.log("");
-    console.log(`  Run \x1b[1moc-inspector restart\x1b[0m to restart`);
-    console.log("");
+    printCommandsHelp();
     return;
   }
 
@@ -254,9 +278,7 @@ async function runDaemonStart(opts) {
     console.log(`  \x1b[32m✓\x1b[0m Dashboard:  http://127.0.0.1:${opts.port}`);
     console.log(`  \x1b[32m✓\x1b[0m Log file:   ${LOG_FILE}`);
     console.log("");
-    console.log(`  \x1b[90mStop with:\x1b[0m  oc-inspector stop`);
-    console.log(`  \x1b[90mView logs:\x1b[0m  oc-inspector logs`);
-    console.log("");
+    printCommandsHelp();
   } else {
     console.log(`  \x1b[31m✗ Failed to start — check logs:\x1b[0m`);
     console.log(`    ${LOG_FILE}`);
@@ -272,11 +294,38 @@ async function runDaemonStart(opts) {
 }
 
 /**
- * Stop the running daemon process.
+ * Stop the running daemon and restore original OpenClaw config.
+ *
+ * Automatically calls `disable` to restore the original provider URLs
+ * and restart the gateway, so OpenClaw doesn't keep routing through
+ * the dead proxy.
  *
  * @param {boolean} [silent=false] - Suppress output (used by restart).
+ * @param {object} [cmdOpts] - CLI opts (for config path).
  */
-function runDaemonStop(silent = false) {
+async function runDaemonStop(silent = false, cmdOpts = {}) {
+  // 1. Restore original config before killing the proxy
+  try {
+    const { detect, disable, status } = await import("../src/config.mjs");
+    const oc = detect(cmdOpts.config);
+    if (oc.exists) {
+      const st = status(oc.dir);
+      if (st.enabled) {
+        const result = disable({ configPath: oc.configPath, openclawDir: oc.dir });
+        if (!silent) {
+          if (result.ok) {
+            console.log(`  \x1b[32m✓\x1b[0m Config restored — ${result.message}`);
+          } else {
+            console.log(`  \x1b[33m⚠\x1b[0m Config restore: ${result.message}`);
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-critical — still kill the process
+  }
+
+  // 2. Kill the daemon process
   const st = getDaemonStatus();
 
   if (!st.pid) {
@@ -292,13 +341,11 @@ function runDaemonStop(silent = false) {
     try {
       process.kill(st.pid, "SIGTERM");
       if (!silent) {
-        console.log("");
         console.log(`  \x1b[32m✓\x1b[0m Stopped inspector (PID ${st.pid})`);
         console.log("");
       }
     } catch (err) {
       if (!silent) {
-        console.log("");
         console.log(`  \x1b[31m✗ Failed to stop PID ${st.pid}: ${err.message}\x1b[0m`);
         console.log("");
       }
@@ -404,8 +451,14 @@ async function runServe(opts) {
     process.exit(1);
   }
 
-  process.on("SIGINT", () => { console.log("\n  Shutting down..."); process.exit(0); });
-  process.on("SIGTERM", () => { console.log("\n  Shutting down (SIGTERM)..."); process.exit(0); });
+  const gracefulShutdown = async (signal) => {
+    console.log(`\n  Shutting down (${signal})...`);
+    await restoreConfigOnExit(opts);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+  process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
 }
 
 /**
@@ -438,8 +491,36 @@ async function runForeground(opts) {
     process.exit(1);
   }
 
-  process.on("SIGINT", () => { console.log("\n  Shutting down..."); process.exit(0); });
-  process.on("SIGTERM", () => process.exit(0));
+  const gracefulShutdown = async (signal) => {
+    console.log(`\n  Shutting down (${signal})...`);
+    await restoreConfigOnExit(opts);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+  process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+}
+
+/**
+ * Restore original OpenClaw config on process exit.
+ * Used by graceful shutdown handlers in _serve and run modes.
+ *
+ * @param {object} cmdOpts - CLI opts (for config path).
+ */
+async function restoreConfigOnExit(cmdOpts = {}) {
+  try {
+    const { detect, disable, status } = await import("../src/config.mjs");
+    const oc = detect(cmdOpts.config);
+    if (oc.exists) {
+      const st = status(oc.dir);
+      if (st.enabled) {
+        const result = disable({ configPath: oc.configPath, openclawDir: oc.dir });
+        console.log(`  \x1b[32m✓\x1b[0m Config restored — ${result.message}`);
+      }
+    }
+  } catch {
+    // Best-effort — don't block exit
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -516,6 +597,10 @@ async function runRemoteCommand(opts) {
   const base = `http://127.0.0.1:${opts.port}`;
 
   if (opts.command === "stats") {
+    if (opts.live) {
+      await runLiveStats(base);
+      return;
+    }
     const data = await fetchApi(`${base}/api/stats`);
     if (!data) return;
     if (opts.json) { console.log(JSON.stringify(data, null, 2)); return; }
@@ -564,6 +649,36 @@ async function runRemoteCommand(opts) {
 // Helpers / Printers
 // ═══════════════════════════════════════════════════════════════
 
+/**
+ * Print a compact command reference table.
+ * Shown after successful daemon start and via `help` command.
+ */
+function printCommandsHelp() {
+  const C = "\x1b[36m";   // cyan
+  const D = "\x1b[90m";   // dim
+  const R = "\x1b[0m";    // reset
+  const B = "\x1b[1m";    // bold
+
+  console.log(`  ${B}Commands:${R}`);
+  console.log(`    ${C}oc-inspector${R}              Start daemon ${D}(default)${R}`);
+  console.log(`    ${C}oc-inspector stop${R}          Stop daemon`);
+  console.log(`    ${C}oc-inspector restart${R}       Restart daemon`);
+  console.log(`    ${C}oc-inspector run${R}           Foreground mode ${D}(interactive)${R}`);
+  console.log(`    ${C}oc-inspector status${R}        Daemon + interception status`);
+  console.log(`    ${C}oc-inspector enable${R}        Enable interception`);
+  console.log(`    ${C}oc-inspector disable${R}       Disable interception`);
+  console.log(`    ${C}oc-inspector stats${R}         Token/cost statistics ${D}(--live for auto-refresh)${R}`);
+  console.log(`    ${C}oc-inspector history${R}       Daily usage history`);
+  console.log(`    ${C}oc-inspector pricing${R}       Model pricing table`);
+  console.log(`    ${C}oc-inspector providers${R}     Active providers list`);
+  console.log(`    ${C}oc-inspector config${R}        Inspector config info`);
+  console.log(`    ${C}oc-inspector logs${R}          Daemon log output`);
+  console.log(`    ${C}oc-inspector help${R}          Show this help`);
+  console.log("");
+  console.log(`  ${D}Use --json for machine-readable output. See oc-inspector --help for all options.${R}`);
+  console.log("");
+}
+
 async function fetchApi(url) {
   try {
     const res = await fetch(url);
@@ -575,64 +690,214 @@ async function fetchApi(url) {
   }
 }
 
+// ── Formatting helpers ──
+
 function fmtNum(n) {
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + "M";
   if (n >= 1_000) return (n / 1_000).toFixed(1) + "k";
   return String(n);
 }
 
-function printStats(s) {
-  const bar = (label, val, max, width = 24) => {
-    const pct = max > 0 ? Math.min(val / max, 1) : 0;
-    const filled = Math.round(pct * width);
-    const empty = width - filled;
-    return `${label}  ${"█".repeat(filled)}${"░".repeat(empty)}  ${fmtNum(val)}`;
-  };
+function fmtCost(n) {
+  if (!n || n === 0) return "$0.00";
+  if (n < 0.01) return "$" + n.toFixed(4);
+  return "$" + n.toFixed(2);
+}
 
-  console.log("");
-  console.log("  \x1b[38;5;208m🦞 OpenClaw Inspector — Stats\x1b[0m");
-  console.log("  " + "─".repeat(50));
-  console.log("");
+function fmtMs(ms) {
+  if (ms >= 60_000) return (ms / 60_000).toFixed(1) + "m";
+  if (ms >= 1_000) return (ms / 1_000).toFixed(1) + "s";
+  return ms + "ms";
+}
+
+/**
+ * Build a horizontal bar string.
+ *
+ * @param {number} val - Current value.
+ * @param {number} max - Maximum value (100%).
+ * @param {number} [width=20] - Bar width in characters.
+ * @returns {string} Bar characters.
+ */
+function bar(val, max, width = 20) {
+  const pct = max > 0 ? Math.min(val / max, 1) : 0;
+  const filled = Math.round(pct * width);
+  const empty = width - filled;
+  return "█".repeat(filled) + "░".repeat(empty);
+}
+
+/**
+ * Render stats data to an array of strings (no ANSI clears).
+ *
+ * @param {object} s - Stats from /api/stats.
+ * @param {object} [opts] - Render options.
+ * @param {boolean} [opts.compact=false] - Skip header/footer.
+ * @returns {string[]} Lines to print.
+ */
+function renderStats(s, { compact = false } = {}) {
+  const lines = [];
+  const w = COL;
+
+  if (!compact) {
+    lines.push("");
+    lines.push(`  ${E.ORG}🦞 OpenClaw Inspector — Stats${E.R}`);
+    lines.push("  " + "─".repeat(68));
+  }
+
+  // ── Summary box ──
+  lines.push("");
+  const errStr = s.errors > 0 ? `  ${E.RED}(${s.errors} errors)${E.R}` : "";
+  lines.push(`  ${E.B}Requests${E.R}     ${String(s.totalRequests).padStart(6)}${errStr}`);
+
+  const inTok = fmtNum(s.totalInputTokens);
+  const outTok = fmtNum(s.totalOutputTokens);
+  lines.push(`  ${E.B}Tokens${E.R}       ${fmtNum(s.totalTokens).padStart(6)}   ${E.D}in ${inTok}  out ${outTok}${E.R}`);
 
-  console.log(`  \x1b[1mRequests:\x1b[0m    ${s.totalRequests}${s.errors > 0 ? `  (\x1b[31m${s.errors} errors\x1b[0m)` : ""}`);
-  console.log(`  \x1b[1mTokens:\x1b[0m      ${fmtNum(s.totalTokens)} total  (in: ${fmtNum(s.totalInputTokens)}  out: ${fmtNum(s.totalOutputTokens)})`);
   if (s.totalCachedTokens > 0) {
-    console.log(`  \x1b[1mCached:\x1b[0m      ${fmtNum(s.totalCachedTokens)}`);
+    lines.push(`  ${E.B}Cached${E.R}       ${fmtNum(s.totalCachedTokens).padStart(6)}`);
   }
-  console.log(`  \x1b[1mCost:\x1b[0m        \x1b[32m$${(s.totalCost || 0).toFixed(4)}\x1b[0m`);
-  if (s.totalDuration > 0) {
-    const avgMs = Math.round(s.totalDuration / s.totalRequests);
-    console.log(`  \x1b[1mAvg latency:\x1b[0m ${avgMs}ms`);
+
+  lines.push(`  ${E.B}Cost${E.R}       ${E.GRN}${fmtCost(s.totalCost || 0).padStart(8)}${E.R}`);
+
+  if (s.totalDuration > 0 && s.totalRequests > 0) {
+    const avg = Math.round(s.totalDuration / s.totalRequests);
+    lines.push(`  ${E.B}Avg latency${E.R}  ${fmtMs(avg).padStart(6)}`);
   }
 
-  const providers = Object.entries(s.byProvider);
+  // ── By Provider ──
+  const providers = Object.entries(s.byProvider || {});
   if (providers.length > 0) {
-    console.log("");
-    console.log("  \x1b[1mBy Provider\x1b[0m");
-    console.log("  " + "─".repeat(50));
-    const maxTokens = Math.max(...providers.map(([, v]) => v.inputTokens + v.outputTokens));
-    for (const [name, v] of providers.sort((a, b) => (b[1].cost || 0) - (a[1].cost || 0) || (b[1].inputTokens + b[1].outputTokens) - (a[1].inputTokens + a[1].outputTokens))) {
-      const total = v.inputTokens + v.outputTokens;
-      const costStr = v.cost > 0 ? `  \x1b[32m$${v.cost.toFixed(4)}\x1b[0m` : "";
-      console.log(`  \x1b[36m${name.padEnd(18)}\x1b[0m ${bar("", total, maxTokens)}  (${v.requests} reqs)${costStr}`);
+    lines.push("");
+    lines.push(`  ${E.B}${"Provider".padEnd(w.name)}  ${"Tokens".padStart(w.tokens)}  ${"Bar".padEnd(w.bar)}  ${"Reqs".padStart(w.reqs)}  ${"Cost".padStart(w.cost)}${E.R}`);
+    lines.push("  " + "─".repeat(68));
+
+    const maxT = Math.max(...providers.map(([, v]) => (v.inputTokens || 0) + (v.outputTokens || 0)));
+    const sorted = providers.sort((a, b) =>
+      (b[1].cost || 0) - (a[1].cost || 0) ||
+      ((b[1].inputTokens || 0) + (b[1].outputTokens || 0)) - ((a[1].inputTokens || 0) + (a[1].outputTokens || 0))
+    );
+
+    for (const [name, v] of sorted) {
+      const total = (v.inputTokens || 0) + (v.outputTokens || 0);
+      const n = name.length > w.name - 2 ? name.slice(0, w.name - 3) + "…" : name;
+      const costStr = v.cost > 0 ? `${E.GRN}${fmtCost(v.cost).padStart(w.cost)}${E.R}` : `${E.D}${fmtCost(0).padStart(w.cost)}${E.R}`;
+      lines.push(`  ${E.CYN}${n.padEnd(w.name)}${E.R}  ${fmtNum(total).padStart(w.tokens)}  ${bar(total, maxT, w.bar)}  ${String(v.requests).padStart(w.reqs)}  ${costStr}`);
     }
   }
 
-  const models = Object.entries(s.byModel);
+  // ── By Model ──
+  const models = Object.entries(s.byModel || {});
   if (models.length > 0) {
-    console.log("");
-    console.log("  \x1b[1mBy Model\x1b[0m");
-    console.log("  " + "─".repeat(50));
-    const maxTokens = Math.max(...models.map(([, v]) => v.inputTokens + v.outputTokens));
-    for (const [name, v] of models.sort((a, b) => (b[1].cost || 0) - (a[1].cost || 0) || (b[1].inputTokens + b[1].outputTokens) - (a[1].inputTokens + a[1].outputTokens))) {
-      const total = v.inputTokens + v.outputTokens;
-      const shortName = name.length > 28 ? name.slice(0, 27) + "…" : name;
-      const costStr = v.cost > 0 ? `  \x1b[32m$${v.cost.toFixed(4)}\x1b[0m` : "";
-      console.log(`  \x1b[33m${shortName.padEnd(30)}\x1b[0m ${bar("", total, maxTokens)}  (${v.requests} reqs)${costStr}`);
+    lines.push("");
+    lines.push(`  ${E.B}${"Model".padEnd(w.name)}  ${"Tokens".padStart(w.tokens)}  ${"Bar".padEnd(w.bar)}  ${"Reqs".padStart(w.reqs)}  ${"Cost".padStart(w.cost)}${E.R}`);
+    lines.push("  " + "─".repeat(68));
+
+    const maxT = Math.max(...models.map(([, v]) => (v.inputTokens || 0) + (v.outputTokens || 0)));
+    const sorted = models.sort((a, b) =>
+      (b[1].cost || 0) - (a[1].cost || 0) ||
+      ((b[1].inputTokens || 0) + (b[1].outputTokens || 0)) - ((a[1].inputTokens || 0) + (a[1].outputTokens || 0))
+    );
+
+    for (const [name, v] of sorted) {
+      const total = (v.inputTokens || 0) + (v.outputTokens || 0);
+      const n = name.length > w.name - 2 ? name.slice(0, w.name - 3) + "…" : name;
+      const costStr = v.cost > 0 ? `${E.GRN}${fmtCost(v.cost).padStart(w.cost)}${E.R}` : `${E.D}${fmtCost(0).padStart(w.cost)}${E.R}`;
+      lines.push(`  ${E.YEL}${n.padEnd(w.name)}${E.R}  ${fmtNum(total).padStart(w.tokens)}  ${bar(total, maxT, w.bar)}  ${String(v.requests).padStart(w.reqs)}  ${costStr}`);
     }
   }
 
-  console.log("");
+  lines.push("");
+  return lines;
+}
+
+function printStats(s) {
+  for (const line of renderStats(s)) process.stdout.write(line + "\n");
+}
+
+/**
+ * Live auto-refreshing stats dashboard.
+ * Clears the terminal and redraws every 2 seconds.
+ * Press q or Ctrl+C to exit.
+ *
+ * @param {string} base - Inspector API base URL.
+ */
+async function runLiveStats(base) {
+  const url = `${base}/api/stats`;
+
+  // Enable raw mode for keypress detection
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+  }
+
+  process.stdout.write(E.HIDE); // hide cursor
+
+  let running = true;
+  let tick = 0;
+
+  const cleanup = () => {
+    running = false;
+    process.stdout.write(E.SHOW); // show cursor
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    console.log("");
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  if (process.stdin.isTTY) {
+    process.stdin.on("data", (key) => {
+      if (key === "q" || key === "Q" || key === "\x03") cleanup(); // q or Ctrl+C
+    });
+  }
+
+  while (running) {
+    try {
+      const res = await fetch(url);
+      const data = await res.json();
+
+      const lines = [];
+      lines.push(E.CLR); // clear screen
+      lines.push(`  ${E.ORG}🦞 OpenClaw Inspector${E.R}  ${E.D}— Live Stats${E.R}`);
+      lines.push("  " + "═".repeat(68));
+
+      // Uptime spinner
+      const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+      const sp = spinner[tick % spinner.length];
+      const now = new Date().toLocaleTimeString();
+      lines.push(`  ${E.GRN}${sp}${E.R} ${E.D}Updated ${now}   Press ${E.B}q${E.R}${E.D} to exit${E.R}`);
+
+      // Render stats body (compact, no header)
+      const body = renderStats(data, { compact: true });
+      lines.push(...body);
+
+      // Recently seen models (last 5 entries by model)
+      const recent = data.recentEntries || [];
+      if (recent.length > 0) {
+        lines.push(`  ${E.B}Recent Requests${E.R}`);
+        lines.push("  " + "─".repeat(68));
+        for (const e of recent.slice(0, 8)) {
+          const model = (e.model || "?").length > 22 ? (e.model || "?").slice(0, 21) + "…" : (e.model || "?");
+          const st = e.state === "done" ? `${E.GRN}✓${E.R}` : e.state === "error" ? `${E.RED}✗${E.R}` : `${E.YEL}…${E.R}`;
+          const dur = e.duration ? fmtMs(e.duration) : "—";
+          const tok = e.totalTokens ? fmtNum(e.totalTokens) : "—";
+          const cost = e.cost > 0 ? `${E.GRN}${fmtCost(e.cost)}${E.R}` : `${E.D}—${E.R}`;
+          lines.push(`  ${st} ${E.YEL}${model.padEnd(24)}${E.R} ${E.CYN}${(e.provider || "?").padEnd(12)}${E.R} ${tok.padStart(8)} tok  ${dur.padStart(6)}  ${cost}`);
+        }
+        lines.push("");
+      }
+
+      process.stdout.write(lines.join("\n") + "\n");
+    } catch {
+      process.stdout.write(E.CLR);
+      process.stdout.write(`\n  ${E.RED}✗ Cannot connect to inspector at ${base}${E.R}\n`);
+      process.stdout.write(`  ${E.D}Retrying...${E.R}\n`);
+    }
+
+    tick++;
+    await new Promise((r) => setTimeout(r, 2000));
+  }
 }
 
 function printPricing(models) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-inspector",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Real-time API traffic inspector for OpenClaw — intercepts LLM provider requests, shows token usage, costs, and message flow in a live web dashboard.",
   "type": "module",
   "bin": {

package/src/config.mjs

@@ -151,9 +151,22 @@ export function restartGateway() {
 export function enable({ configPath, openclawDir, port }) {
   const proxyBase = `http://127.0.0.1:${port}`;
 
-  // 1. Backup
+  // 0. Guard: if already enabled, refuse to double-enable
+  //    This prevents overwriting originals with proxy URLs.
+  const existingState = readState(openclawDir);
+  if (existingState?.enabled && Object.keys(existingState.originals || {}).length > 0) {
+    return {
+      ok: true,
+      message: "Already enabled",
+      providers: Object.keys(existingState.originals),
+    };
+  }
+
+  // 1. Backup — only if no existing backup (prevents overwriting clean backup)
   const backupPath = configPath + ".inspector-backup";
-  copyFileSync(configPath, backupPath);
+  if (!existsSync(backupPath)) {
+    copyFileSync(configPath, backupPath);
+  }
 
   // 2. Read config
   const config = readConfig(configPath);
@@ -170,6 +183,13 @@ export function enable({ configPath, openclawDir, port }) {
       originals[name] = { baseUrl: cfg.baseUrl, wasCustom: true };
       cfg.baseUrl = `${proxyBase}/${name}`;
       enabled.push(name);
+    } else if (cfg.baseUrl && cfg.baseUrl.startsWith(proxyBase)) {
+      // Already proxied — skip but don't lose the original
+      // Try to resolve from BUILTIN_URLS
+      if (BUILTIN_URLS[name]) {
+        originals[name] = { baseUrl: BUILTIN_URLS[name], wasCustom: true };
+      }
+      enabled.push(name);
     }
   }
 
@@ -187,7 +207,16 @@ export function enable({ configPath, openclawDir, port }) {
     enabled.push(name);
   }
 
-  // 5. Save state for restore
+  // 5. Validate: refuse to save if originals is empty (means nothing to restore)
+  if (Object.keys(originals).length === 0 && enabled.length === 0) {
+    return {
+      ok: false,
+      message: "No providers found to intercept",
+      providers: [],
+    };
+  }
+
+  // 6. Save state for restore
   writeState(openclawDir, {
     enabled: true,
     port,
@@ -196,10 +225,10 @@ export function enable({ configPath, openclawDir, port }) {
     backupPath,
   });
 
-  // 6. Write patched config
+  // 7. Write patched config
   writeConfig(configPath, config);
 
-  // 7. Restart gateway
+  // 8. Restart gateway
   const restart = restartGateway();
 
   return {
@@ -222,27 +251,49 @@ export function enable({ configPath, openclawDir, port }) {
 export function disable({ configPath, openclawDir }) {
   const state = readState(openclawDir);
 
-  if (!state || !state.originals) {
-    // Try restoring from backup
-    const backupPath = configPath + ".inspector-backup";
+  const hasOriginals = state?.originals && Object.keys(state.originals).length > 0;
+
+  if (!hasOriginals) {
+    // No valid originals — try restoring from backup file
+    const backupPath = state?.backupPath || configPath + ".inspector-backup";
     if (existsSync(backupPath)) {
-      copyFileSync(backupPath, configPath);
+      // Verify backup is clean (doesn't contain proxy URLs)
+      try {
+        const backupContent = readFileSync(backupPath, "utf-8");
+        if (!backupContent.includes("127.0.0.1:18800")) {
+          copyFileSync(backupPath, configPath);
+          removeState(openclawDir);
+          const restart = restartGateway();
+          return {
+            ok: restart.ok,
+            message: restart.ok ? "Restored from clean backup" : "Restored config but gateway restart failed",
+          };
+        }
+        // Backup is also corrupted — fall through to manual cleanup
+      } catch { /* ignore */ }
+    }
+
+    // Last resort: scan config for proxy URLs and replace with BUILTIN_URLS
+    const cleaned = cleanProxyUrls(configPath);
+    if (cleaned) {
+      removeState(openclawDir);
       const restart = restartGateway();
       return {
         ok: restart.ok,
-        message: restart.ok ? "Restored from backup" : `Restored config but gateway restart failed`,
+        message: restart.ok ? "Cleaned proxy URLs from config" : "Config cleaned but gateway restart failed",
       };
     }
-    return { ok: false, message: "No inspector state found — nothing to restore" };
+
+    removeState(openclawDir);
+    return { ok: false, message: "No inspector state or backup found — nothing to restore" };
   }
 
-  // Read current config and restore originals
+  // Happy path: restore from originals
   const config = readConfig(configPath);
   const providers = config.models?.providers || {};
 
   for (const [name, orig] of Object.entries(state.originals)) {
     if (orig.wasCustom) {
-      // Restore original baseUrl
       if (providers[name]) {
         providers[name].baseUrl = orig.baseUrl;
       }
@@ -253,10 +304,12 @@ export function disable({ configPath, openclawDir }) {
   }
 
   writeConfig(configPath, config);
-
-  // Clean up state file
   removeState(openclawDir);
 
+  // Clean up backup file
+  const backupPath = state?.backupPath || configPath + ".inspector-backup";
+  try { if (existsSync(backupPath)) unlinkSync(backupPath); } catch { /* ignore */ }
+
   const restart = restartGateway();
 
   return {
@@ -265,6 +318,46 @@ export function disable({ configPath, openclawDir }) {
   };
 }
 
+/**
+ * Emergency cleanup: scan config for proxy URLs and replace with known originals.
+ *
+ * @param {string} configPath - Path to openclaw.json.
+ * @returns {boolean} True if any cleanup was performed.
+ */
+function cleanProxyUrls(configPath) {
+  try {
+    const config = readConfig(configPath);
+    const providers = config.models?.providers || {};
+    let cleaned = false;
+
+    for (const [name, cfg] of Object.entries(providers)) {
+      if (cfg.baseUrl && cfg.baseUrl.includes("127.0.0.1:18800")) {
+        if (BUILTIN_URLS[name]) {
+          // Known provider — restore builtin URL
+          cfg.baseUrl = BUILTIN_URLS[name];
+          cleaned = true;
+        } else if (cfg.models && cfg.models.length > 0) {
+          // Custom provider with models — remove the broken baseUrl
+          // Can't know original URL, but removing it is better than dead proxy
+          delete cfg.baseUrl;
+          cleaned = true;
+        } else {
+          // Empty provider entry added by inspector — remove entirely
+          delete providers[name];
+          cleaned = true;
+        }
+      }
+    }
+
+    if (cleaned) {
+      writeConfig(configPath, config);
+    }
+    return cleaned;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check current interception status.
  *

package/src/proxy.mjs

@@ -112,6 +112,24 @@ export function getStats() {
     }
   }
 
+  // Recent entries (last 10) for live view
+  const recentEntries = [];
+  const recentIds = entryOrder.slice(-10).reverse();
+  for (const id of recentIds) {
+    const e = entries.get(id);
+    if (!e) continue;
+    const u = e.usage || {};
+    recentEntries.push({
+      id: e.id,
+      provider: e.provider || "?",
+      model: u.model || e.reqModel || "?",
+      state: e.state,
+      duration: e.duration || 0,
+      totalTokens: (u.inputTokens || 0) + (u.outputTokens || 0),
+      cost: e.cost || 0,
+    });
+  }
+
   return {
     totalRequests,
     totalInputTokens,
@@ -123,6 +141,7 @@ export function getStats() {
     errors,
     byProvider,
     byModel,
+    recentEntries,
   };
 }