oc-inspector 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# 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.
+
+## Quick Start
+
+```bash
+npx oc-inspector
+```
+
+This starts the inspector proxy on port 18800 and opens a web dashboard.
+
+## Features
+
+- **One-click enable/disable** — patches OpenClaw config automatically, no manual editing
+- **All providers** — Anthropic, OpenAI, BytePlus, Ollama, Groq, Mistral, xAI, OpenRouter, and any custom provider
+- **Real-time dashboard** — WebSocket-powered live view of every API request and response
+- **Token tracking** — accurate token counts for streaming (SSE) and non-streaming responses
+- **Cost estimation** — per-request cost based on model pricing
+- **Message inspector** — view system prompts, tool calls, thinking blocks, and full conversation history
+- **Zero dependencies on OpenClaw internals** — works as a standalone reverse proxy
+
+## Usage
+
+```bash
+# Start with defaults (port 18800)
+npx oc-inspector
+
+# Custom port
+npx oc-inspector --port 9000
+
+# Auto-open browser
+npx oc-inspector --open
+
+# Custom OpenClaw config path
+npx oc-inspector --config /path/to/openclaw.json
+```
+
+## How It Works
+
+1. The inspector starts an HTTP reverse proxy on `localhost:18800`
+2. Click **Enable** in the web UI — it patches `openclaw.json` to route all providers through the proxy and restarts the gateway
+3. All LLM API traffic flows through the inspector, which logs requests/responses and extracts token usage
+4. Click **Disable** to restore the original config
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for @kshidenko/openclaw-inspector.
+ *
+ * Usage:
+ *   npx @kshidenko/openclaw-inspector [options]
+ *
+ * Options:
+ *   --port <number>   Port for the inspector proxy (default: 18800)
+ *   --open            Auto-open the dashboard in a browser
+ *   --config <path>   Custom path to openclaw.json
+ *   --help            Show help message
+ */
+
+import { startServer } from "../src/server.mjs";
+
+const args = process.argv.slice(2);
+
+/** Parse a simple --key value or --flag argument list. */
+function parseArgs(argv) {
+  const opts = { port: 18800, open: false, config: undefined, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--port" && argv[i + 1]) {
+      opts.port = parseInt(argv[++i], 10);
+    } else if (arg === "--open") {
+      opts.open = true;
+    } else if (arg === "--config" && argv[i + 1]) {
+      opts.config = argv[++i];
+    } else if (arg === "--help" || arg === "-h") {
+      opts.help = true;
+    }
+  }
+  return opts;
+}
+
+const opts = parseArgs(args);
+
+if (opts.help) {
+  console.log(`
+  oc-inspector — Real-time API traffic inspector for OpenClaw
+
+  Usage:
+    npx oc-inspector [options]
+
+  Options:
+    --port <number>   Port for the inspector proxy (default: 18800)
+    --open            Auto-open the dashboard in a browser
+    --config <path>   Custom path to openclaw.json
+    --help, -h        Show this help message
+
+  Once running, open http://localhost:<port> in your browser.
+  Click "Enable" to start intercepting OpenClaw API traffic.
+`);
+  process.exit(0);
+}
+
+console.log("");
+console.log("  \x1b[38;5;208m🦞 OpenClaw Inspector\x1b[0m");
+console.log("");
+
+try {
+  const { url, openclawDir } = await startServer({
+    port: opts.port,
+    configPath: opts.config,
+    open: opts.open,
+  });
+
+  console.log(`  \x1b[32m✓\x1b[0m Dashboard:  ${url}`);
+  console.log(`  \x1b[32m✓\x1b[0m Config:     ${openclawDir}/openclaw.json`);
+  console.log(`  \x1b[32m✓\x1b[0m Proxy port: ${opts.port}`);
+  console.log("");
+  console.log("  Press \x1b[1mCtrl+C\x1b[0m to stop");
+  console.log("");
+} catch (err) {
+  console.error(`\x1b[31m  ✗ Failed to start: ${err.message}\x1b[0m`);
+  process.exit(1);
+}
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+  console.log("\n  Shutting down...");
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "oc-inspector",
+  "version": "1.0.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": {
+    "oc-inspector": "./bin/cli.mjs"
+  },
+  "main": "./src/server.mjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/cli.mjs",
+    "dev": "node bin/cli.mjs --open"
+  },
+  "keywords": [
+    "openclaw",
+    "llm",
+    "inspector",
+    "proxy",
+    "anthropic",
+    "openai",
+    "token-usage",
+    "api-monitor"
+  ],
+  "author": "kshidenko",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kshidenko/openclaw-inspector"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}

package/src/config.mjs

@@ -0,0 +1,284 @@
+/**
+ * OpenClaw config manager for the Inspector.
+ *
+ * Handles detection of the OpenClaw installation, reading/patching/restoring
+ * openclaw.json to route provider traffic through the inspector proxy,
+ * and restarting the gateway.
+ *
+ * @module config
+ */
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { BUILTIN_URLS, detectActiveProviders } from "./providers.mjs";
+
+/** Default OpenClaw state directory. */
+const DEFAULT_OPENCLAW_DIR = join(homedir(), ".openclaw");
+
+/** Filename for the main config. */
+const CONFIG_FILENAME = "openclaw.json";
+
+/** Filename for the inspector state (stores original URLs for restore). */
+const STATE_FILENAME = ".inspector-state.json";
+
+/**
+ * Detect the OpenClaw directory and config file path.
+ *
+ * @param {string} [customPath] - Optional explicit path to openclaw.json.
+ * @returns {{ dir: string, configPath: string, exists: boolean }}
+ *
+ * Example:
+ *   >>> detect()
+ *   { dir: "/Users/me/.openclaw", configPath: "/Users/me/.openclaw/openclaw.json", exists: true }
+ */
+export function detect(customPath) {
+  if (customPath) {
+    const dir = customPath.endsWith(CONFIG_FILENAME)
+      ? customPath.slice(0, -CONFIG_FILENAME.length - 1)
+      : customPath;
+    const configPath = customPath.endsWith(".json") ? customPath : join(customPath, CONFIG_FILENAME);
+    return { dir, configPath, exists: existsSync(configPath) };
+  }
+
+  // Check OPENCLAW_STATE_DIR env, then default
+  const stateDir = process.env.OPENCLAW_STATE_DIR || DEFAULT_OPENCLAW_DIR;
+  const configPath = join(stateDir, CONFIG_FILENAME);
+  return { dir: stateDir, configPath, exists: existsSync(configPath) };
+}
+
+/**
+ * Read and parse openclaw.json.
+ *
+ * @param {string} configPath - Full path to openclaw.json.
+ * @returns {object} Parsed config object.
+ * @throws {Error} If file cannot be read or parsed.
+ */
+export function readConfig(configPath) {
+  const raw = readFileSync(configPath, "utf-8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Write config object back to openclaw.json.
+ *
+ * @param {string} configPath - Full path to openclaw.json.
+ * @param {object} config - Config object to serialize.
+ */
+function writeConfig(configPath, config) {
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Read the inspector state file (stores original provider URLs).
+ *
+ * @param {string} openclawDir - Path to ~/.openclaw.
+ * @returns {object|null} State object or null if not found.
+ */
+function readState(openclawDir) {
+  const statePath = join(openclawDir, STATE_FILENAME);
+  if (!existsSync(statePath)) return null;
+  try {
+    return JSON.parse(readFileSync(statePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the inspector state file.
+ *
+ * @param {string} openclawDir - Path to ~/.openclaw.
+ * @param {object} state - State object to persist.
+ */
+function writeState(openclawDir, state) {
+  const statePath = join(openclawDir, STATE_FILENAME);
+  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Remove the inspector state file.
+ *
+ * @param {string} openclawDir - Path to ~/.openclaw.
+ */
+function removeState(openclawDir) {
+  const statePath = join(openclawDir, STATE_FILENAME);
+  if (existsSync(statePath)) {
+    unlinkSync(statePath);
+  }
+}
+
+/**
+ * Restart the OpenClaw gateway via CLI.
+ *
+ * @returns {{ ok: boolean, output: string }}
+ */
+export function restartGateway() {
+  try {
+    const output = execSync("openclaw gateway restart", {
+      encoding: "utf-8",
+      timeout: 15_000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { ok: true, output };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.message };
+  }
+}
+
+/**
+ * Enable interception: patch openclaw.json to route all providers through
+ * the inspector proxy.
+ *
+ * Steps:
+ *   1. Create backup of openclaw.json
+ *   2. Detect active providers (from auth-profiles + config)
+ *   3. Save original URLs to .inspector-state.json
+ *   4. Patch config: set baseUrl to proxy for each provider
+ *   5. Restart gateway
+ *
+ * @param {object} params
+ * @param {string} params.configPath - Path to openclaw.json.
+ * @param {string} params.openclawDir - Path to ~/.openclaw.
+ * @param {number} params.port - Inspector proxy port.
+ * @returns {{ ok: boolean, message: string, providers: string[] }}
+ *
+ * Example:
+ *   >>> enable({ configPath: "~/.openclaw/openclaw.json", openclawDir: "~/.openclaw", port: 18800 })
+ *   { ok: true, message: "Enabled 3 providers", providers: ["anthropic", "byteplus", "ollama"] }
+ */
+export function enable({ configPath, openclawDir, port }) {
+  const proxyBase = `http://127.0.0.1:${port}`;
+
+  // 1. Backup
+  const backupPath = configPath + ".inspector-backup";
+  copyFileSync(configPath, backupPath);
+
+  // 2. Read config
+  const config = readConfig(configPath);
+  if (!config.models) config.models = {};
+  if (!config.models.providers) config.models.providers = {};
+
+  const providers = config.models.providers;
+  const originals = {}; // provider -> original baseUrl or null (for built-in)
+  const enabled = [];
+
+  // 3. Patch custom providers (already have baseUrl in config)
+  for (const [name, cfg] of Object.entries(providers)) {
+    if (cfg.baseUrl && !cfg.baseUrl.startsWith(proxyBase)) {
+      originals[name] = { baseUrl: cfg.baseUrl, wasCustom: true };
+      cfg.baseUrl = `${proxyBase}/${name}`;
+      enabled.push(name);
+    }
+  }
+
+  // 4. Add built-in providers that have auth but no config entry yet
+  const active = detectActiveProviders(openclawDir);
+  for (const name of active) {
+    if (providers[name]) continue; // Already patched above
+    if (!BUILTIN_URLS[name]) continue; // Unknown provider
+
+    originals[name] = { baseUrl: BUILTIN_URLS[name], wasCustom: false };
+    providers[name] = {
+      baseUrl: `${proxyBase}/${name}`,
+      models: [],
+    };
+    enabled.push(name);
+  }
+
+  // 5. Save state for restore
+  writeState(openclawDir, {
+    enabled: true,
+    port,
+    timestamp: new Date().toISOString(),
+    originals,
+    backupPath,
+  });
+
+  // 6. Write patched config
+  writeConfig(configPath, config);
+
+  // 7. Restart gateway
+  const restart = restartGateway();
+
+  return {
+    ok: restart.ok,
+    message: restart.ok
+      ? `Enabled ${enabled.length} providers`
+      : `Config patched but gateway restart failed: ${restart.output}`,
+    providers: enabled,
+  };
+}
+
+/**
+ * Disable interception: restore openclaw.json to original state.
+ *
+ * @param {object} params
+ * @param {string} params.configPath - Path to openclaw.json.
+ * @param {string} params.openclawDir - Path to ~/.openclaw.
+ * @returns {{ ok: boolean, message: string }}
+ */
+export function disable({ configPath, openclawDir }) {
+  const state = readState(openclawDir);
+
+  if (!state || !state.originals) {
+    // Try restoring from backup
+    const backupPath = configPath + ".inspector-backup";
+    if (existsSync(backupPath)) {
+      copyFileSync(backupPath, configPath);
+      const restart = restartGateway();
+      return {
+        ok: restart.ok,
+        message: restart.ok ? "Restored from backup" : `Restored config but gateway restart failed`,
+      };
+    }
+    return { ok: false, message: "No inspector state found — nothing to restore" };
+  }
+
+  // Read current config and restore 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;
+      }
+    } else {
+      // Remove the entry we added for built-in providers
+      delete providers[name];
+    }
+  }
+
+  writeConfig(configPath, config);
+
+  // Clean up state file
+  removeState(openclawDir);
+
+  const restart = restartGateway();
+
+  return {
+    ok: restart.ok,
+    message: restart.ok ? "Disabled — config restored" : "Config restored but gateway restart failed",
+  };
+}
+
+/**
+ * Check current interception status.
+ *
+ * @param {string} openclawDir - Path to ~/.openclaw.
+ * @returns {{ enabled: boolean, providers: string[], port: number|null }}
+ */
+export function status(openclawDir) {
+  const state = readState(openclawDir);
+  if (!state || !state.enabled) {
+    return { enabled: false, providers: [], port: null };
+  }
+  return {
+    enabled: true,
+    providers: Object.keys(state.originals || {}),
+    port: state.port || null,
+  };
+}