@elvatis_com/openclaw-cli-bridge-elvatis 0.2.2 → 0.2.4

package/README.md

@@ -1,83 +1,190 @@
 # openclaw-cli-bridge-elvatis
 
-> OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers.
+> OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers — with slash commands for instant model switching.
+
+**Current version:** `0.2.2`
+
+---
 
 ## What it does
 
-**Phase 1 — Auth bridge:** Registers the `openai-codex` provider using OAuth tokens already stored by the Codex CLI (`~/.codex/auth.json`). No re-login needed.
+### Phase 1 — Auth bridge (`openai-codex`)
+Registers the `openai-codex` provider by reading OAuth tokens already stored by the Codex CLI (`~/.codex/auth.json`). No re-login needed.
+
+### Phase 2 — Request bridge (local proxy)
+Starts a local OpenAI-compatible HTTP proxy on `127.0.0.1:31337` and configures OpenClaw's `vllm` provider to route calls through `gemini` and `claude` CLI subprocesses.
 
-**Phase 2 — Request bridge:** Starts a local OpenAI-compatible HTTP proxy server (default port `31337`) and configures OpenClaw's `vllm` provider to route model calls through `gemini` and `claude` CLI subprocesses.
+Prompt delivery: always via **stdin** (not CLI args) — avoids `E2BIG` for long sessions. Each message batch is truncated to the last 20 messages + system message (configurable in `src/cli-runner.ts`).
 
 | Model reference | CLI invoked |
 |---|---|
-| `vllm/cli-gemini/gemini-2.5-pro` | `gemini -m gemini-2.5-pro -p "<prompt>"` |
-| `vllm/cli-gemini/gemini-2.5-flash` | `gemini -m gemini-2.5-flash -p "<prompt>"` |
-| `vllm/cli-claude/claude-opus-4-6` | `claude -p -m claude-opus-4-6 --output-format text "<prompt>"` |
-| `vllm/cli-claude/claude-sonnet-4-6` | `claude -p -m claude-sonnet-4-6 --output-format text "<prompt>"` |
+| `vllm/cli-gemini/gemini-2.5-pro` | `gemini -m gemini-2.5-pro @<tmpfile>` |
+| `vllm/cli-gemini/gemini-2.5-flash` | `gemini -m gemini-2.5-flash @<tmpfile>` |
+| `vllm/cli-gemini/gemini-3-pro` | `gemini -m gemini-3-pro @<tmpfile>` |
+| `vllm/cli-claude/claude-sonnet-4-6` | `claude -p --output-format text --model claude-sonnet-4-6` (stdin) |
+| `vllm/cli-claude/claude-opus-4-6` | `claude -p --output-format text --model claude-opus-4-6` (stdin) |
+| `vllm/cli-claude/claude-haiku-4-5` | `claude -p --output-format text --model claude-haiku-4-5` (stdin) |
+
+### Phase 3 — Slash commands
+Six plugin-registered commands for instant model switching (no agent invocation needed):
+
+| Command | Switches to |
+|---|---|
+| `/cli-sonnet` | `vllm/cli-claude/claude-sonnet-4-6` |
+| `/cli-opus` | `vllm/cli-claude/claude-opus-4-6` |
+| `/cli-haiku` | `vllm/cli-claude/claude-haiku-4-5` |
+| `/cli-gemini` | `vllm/cli-gemini/gemini-2.5-pro` |
+| `/cli-gemini-flash` | `vllm/cli-gemini/gemini-2.5-flash` |
+| `/cli-gemini3` | `vllm/cli-gemini/gemini-3-pro` |
+
+All commands require `requireAuth: true` — only authorized/owner senders can execute them. Each command calls `openclaw models set <model>` via `api.runtime.system.runCommandWithTimeout` and replies with a confirmation.
+
+---
 
 ## Requirements
 
-- [OpenClaw](https://openclaw.ai) gateway running
+- [OpenClaw](https://openclaw.ai) gateway (tested with `2026.3.x`)
 - One or more of:
   - [`@openai/codex`](https://github.com/openai/codex) — `npm i -g @openai/codex` + `codex login`
   - [`@google/gemini-cli`](https://github.com/google-gemini/gemini-cli) — `npm i -g @google/gemini-cli` + `gemini auth`
   - [`@anthropic-ai/claude-code`](https://github.com/anthropic-ai/claude-code) — `npm i -g @anthropic-ai/claude-code` + `claude auth`
 
+---
+
 ## Installation
 
 ```bash
-# Install from ClawHub (once published)
+# From ClawHub
 clawhub install openclaw-cli-bridge-elvatis
 
-# Or load directly from this repo (development)
+# Or from workspace (development / local path)
 # Add to ~/.openclaw/openclaw.json:
-# plugins.load.paths: ["<path-to-this-repo>"]
-# plugins.allow: ["openclaw-cli-bridge-elvatis"]
+# plugins.load.paths: ["~/.openclaw/workspace/openclaw-cli-bridge-elvatis"]
 # plugins.entries.openclaw-cli-bridge-elvatis: { "enabled": true }
 ```
 
-## Auth setup (Phase 1 — Codex)
+---
+
+## Setup
+
+### 1. Enable + restart
 
-After enabling the plugin, register the Codex auth profile:
+```bash
+# In ~/.openclaw/openclaw.json → plugins.entries:
+"openclaw-cli-bridge-elvatis": { "enabled": true }
+
+openclaw gateway restart
+```
+
+### 2. Register Codex auth (Phase 1, optional)
 
 ```bash
 openclaw models auth login --provider openai-codex
 # Select: "Codex CLI (existing login)"
 ```
 
-The proxy server (Phase 2) starts automatically and patches `openclaw.json` with the `vllm` provider config. Restart the gateway to activate the new models.
+### 3. Verify proxy (Phase 2)
+
+On startup the plugin auto-patches `openclaw.json` with the `vllm` provider config (port `31337`) and logs:
+
+```
+[cli-bridge] proxy ready — vllm/cli-gemini/* and vllm/cli-claude/* available
+[cli-bridge] registered 6 slash commands: /cli-sonnet, /cli-opus, /cli-haiku, /cli-gemini, /cli-gemini-flash, /cli-gemini3
+```
+
+### 4. Switch models (Phase 3)
+
+Use any `/cli-*` command from any connected channel:
+
+```
+/cli-sonnet
+→ ✅ Switched to Claude Sonnet 4.6 (CLI)
+   `vllm/cli-claude/claude-sonnet-4-6`
+```
+
+---
 
 ## Configuration
 
-Add to your `plugins.entries.openclaw-cli-bridge-elvatis.config` in `~/.openclaw/openclaw.json`:
+In `~/.openclaw/openclaw.json` → `plugins.entries.openclaw-cli-bridge-elvatis.config`:
 
 ```json5
 {
-  "enableCodex": true,       // register openai-codex from Codex CLI auth
-  "enableProxy": true,       // start the local CLI proxy server
-  "proxyPort": 31337,        // port for the proxy (default: 31337)
-  "proxyApiKey": "cli-bridge", // key used between OpenClaw and the proxy
-  "proxyTimeoutMs": 120000   // CLI timeout in ms (default: 2 min)
+  "enableCodex": true,         // register openai-codex from Codex CLI auth (default: true)
+  "enableProxy": true,         // start local CLI proxy server (default: true)
+  "proxyPort": 31337,          // proxy port (default: 31337)
+  "proxyApiKey": "cli-bridge", // key between OpenClaw vllm provider and proxy (default: "cli-bridge")
+  "proxyTimeoutMs": 120000     // CLI subprocess timeout in ms (default: 120s)
 }
 ```
 
+---
+
 ## Architecture
 
 ```
 OpenClaw agent
   │
-  ├─ openai-codex/* ──► OpenAI API (auth via Codex CLI OAuth tokens)
+  ├─ openai-codex/*  ──► OpenAI API  (auth via ~/.codex/auth.json OAuth tokens)
   │
   └─ vllm/cli-gemini/*  ─┐
-     vllm/cli-claude/*   ─┤─► openclaw-cli-bridge-elvatis proxy (127.0.0.1:31337)
-                          │       ├─ cli-gemini/* → gemini -m <model> -p "<prompt>"
-                          │       └─ cli-claude/* → claude -p -m <model> "<prompt>"
-                          └──────────────────────────────────────────────────────
+     vllm/cli-claude/*   ─┤─► localhost:31337  (openclaw-cli-bridge proxy)
+                          │       ├─ cli-gemini/* → gemini -m <model> @<tmpfile>
+                          │       └─ cli-claude/* → claude -p --model <model>  ← prompt via stdin
+                          └───────────────────────────────────────────────────
+
+Slash commands (bypass agent):
+  /cli-sonnet|opus|haiku|gemini|gemini-flash|gemini3
+     └─► openclaw models set <model>  (atomic, ~1s)
 ```
 
-## AAHP handoff
+---
+
+## Known Issues & Fixes
+
+### `spawn E2BIG` (fixed in v0.2.1)
+
+**Symptom:** `CLI error for cli-claude/…: spawn E2BIG` after ~500+ messages in a session.
+
+**Root cause:** The OpenClaw gateway modifies `process.env` at runtime (OPENCLAW_* vars, session context, etc.). Spreading the full `process.env` into `spawn()` pushes `argv + envp` over Linux's `ARG_MAX` (~2MB).
+
+**Fix:** `buildMinimalEnv()` in `src/cli-runner.ts` — only passes `HOME`, `PATH`, `USER`, and auth keys to the subprocess. Immune to gateway runtime env size.
+
+---
+
+## Development
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+```
+
+Test coverage: `test/cli-runner.test.ts` — unit tests for `formatPrompt` (truncation, system message handling, MAX_MSG_CHARS).
+
+---
+
+## Changelog
+
+### v0.2.2
+- **feat:** Phase 3 — `/cli-*` slash commands for instant model switching
+- All 6 commands registered via `api.registerCommand` with `requireAuth: true`
+- Calls `openclaw models set <model>` via `api.runtime.system.runCommandWithTimeout`
+
+### v0.2.1
+- **fix:** `spawn E2BIG` — use `buildMinimalEnv()` instead of spreading full `process.env`
+- **feat:** Added `test/cli-runner.test.ts` (5 unit tests)
+- Added Gemini 3 Pro model (`vllm/cli-gemini/gemini-3-pro`)
+
+### v0.2.0
+- **feat:** Phase 2 — local OpenAI-compatible proxy server
+- Prompt via stdin/tmpfile (never as CLI arg) to prevent arg-size issues
+- `MAX_MESSAGES=20` + `MAX_MSG_CHARS=4000` truncation in `formatPrompt`
+- Auto-patch of `openclaw.json` vllm provider config on first start
+
+### v0.1.x
+- Phase 1: Codex CLI OAuth auth bridge
 
-Project tracking lives in `.ai/handoff/` (AAHP v3 protocol).
+---
 
 ## License
 

package/SKILL.md

@@ -1,24 +1,52 @@
 ---
 name: openclaw-cli-bridge-elvatis
-description: Bridge local Codex, Gemini, and Claude Code CLIs into OpenClaw (Codex OAuth auth bridge + Gemini/Claude OpenAI-compatible local proxy via vllm).
+description: Bridge local Codex, Gemini, and Claude Code CLIs into OpenClaw as vllm model providers. Includes /cli-* slash commands for instant model switching (/cli-sonnet, /cli-opus, /cli-haiku, /cli-gemini, /cli-gemini-flash, /cli-gemini3). E2BIG-safe spawn via minimal env.
 homepage: https://github.com/elvatis/openclaw-cli-bridge-elvatis
 metadata:
   {
     "openclaw":
       {
         "emoji": "🌉",
-        "requires": { "bins": ["openclaw", "codex", "gemini", "claude"] }
+        "requires": { "bins": ["openclaw", "claude", "gemini"] },
+        "commands": ["/cli-sonnet", "/cli-opus", "/cli-haiku", "/cli-gemini", "/cli-gemini-flash", "/cli-gemini3"]
       }
   }
 ---
 
-# OpenClaw CLI Bridge Elvatis
+# OpenClaw CLI Bridge
 
-This project provides two layers:
+Bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as OpenClaw model providers. Three phases:
 
-1. **Codex auth bridge** for `openai-codex/*` by reading existing Codex CLI OAuth tokens from `~/.codex/auth.json`
-2. **Local OpenAI-compatible proxy** (default `127.0.0.1:31337`) for Gemini/Claude CLI execution via OpenClaw `vllm` provider models:
-   - `vllm/cli-gemini/*`
-   - `vllm/cli-claude/*`
+## Phase 1 — Codex Auth Bridge
+Registers `openai-codex` provider from existing `~/.codex/auth.json` tokens. No re-login.
 
-See `README.md` for setup and architecture.
+## Phase 2 — Request Proxy
+Local OpenAI-compatible HTTP proxy (`127.0.0.1:31337`) routes vllm model calls to CLI subprocesses:
+- `vllm/cli-gemini/gemini-2.5-pro` / `gemini-2.5-flash` / `gemini-3-pro`
+- `vllm/cli-claude/claude-sonnet-4-6` / `claude-opus-4-6` / `claude-haiku-4-5`
+
+Prompts go via stdin/tmpfile — never as CLI args (prevents `E2BIG` for long sessions).
+
+## Phase 3 — Slash Commands
+Six instant model-switch commands (authorized senders only):
+
+| Command | Model |
+|---|---|
+| `/cli-sonnet` | `vllm/cli-claude/claude-sonnet-4-6` |
+| `/cli-opus` | `vllm/cli-claude/claude-opus-4-6` |
+| `/cli-haiku` | `vllm/cli-claude/claude-haiku-4-5` |
+| `/cli-gemini` | `vllm/cli-gemini/gemini-2.5-pro` |
+| `/cli-gemini-flash` | `vllm/cli-gemini/gemini-2.5-flash` |
+| `/cli-gemini3` | `vllm/cli-gemini/gemini-3-pro` |
+
+Each command runs `openclaw models set <model>` atomically and replies with a confirmation.
+
+## Setup
+
+1. Enable plugin + restart gateway
+2. (Optional) Register Codex auth: `openclaw models auth login --provider openai-codex`
+3. Use `/cli-*` commands to switch models from any channel
+
+See `README.md` for full configuration reference and architecture diagram.
+
+**Version:** 0.2.2

package/index.ts

@@ -15,23 +15,27 @@
  *   /cli-gemini       → vllm/cli-gemini/gemini-2.5-pro
  *   /cli-gemini-flash → vllm/cli-gemini/gemini-2.5-flash
  *   /cli-gemini3      → vllm/cli-gemini/gemini-3-pro
+ *   /cli-back         → restore model that was active before last /cli-* switch
+ *   /cli-test [model] → one-shot proxy health check (does NOT switch global model)
  *
  * Provider / model naming:
- *   vllm/cli-gemini/gemini-2.5-pro  → `gemini -m gemini-2.5-pro -p "<prompt>"`
- *   vllm/cli-claude/claude-opus-4-6 → `claude -p -m claude-opus-4-6 --output-format text "<prompt>"`
+ *   vllm/cli-gemini/gemini-2.5-pro  → `gemini -m gemini-2.5-pro @<tmpfile>`
+ *   vllm/cli-claude/claude-opus-4-6 → `claude -p -m claude-opus-4-6 --output-format text` (stdin)
  */
 
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import http from "node:http";
 import type {
   OpenClawPluginApi,
   ProviderAuthContext,
   ProviderAuthResult,
 } from "openclaw/plugin-sdk";
 
-// Types derived from the plugin SDK (PluginCommandContext / PluginCommandResult are
-// not re-exported from the package, so we infer them from the registerCommand signature).
-type RegisterCommandParam = Parameters<OpenClawPluginApi["registerCommand"]>[0];
-type PluginCommandContext = Parameters<RegisterCommandParam["handler"]>[0];
-type PluginCommandResult = Awaited<ReturnType<RegisterCommandParam["handler"]>>;
+// OpenClawPluginCommandDefinition is defined in the SDK types but not re-exported
+// by the package — derive it from the registerCommand signature.
+type OpenClawPluginCommandDefinition = Parameters<OpenClawPluginApi["registerCommand"]>[0];
 import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk";
 import {
   DEFAULT_CODEX_AUTH_PATH,
@@ -41,14 +45,19 @@ import {
 import { startProxyServer } from "./src/proxy-server.js";
 import { patchOpencllawConfig } from "./src/config-patcher.js";
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Types derived from SDK (not re-exported by the package)
+// ──────────────────────────────────────────────────────────────────────────────
+type RegisterCommandParam = Parameters<OpenClawPluginApi["registerCommand"]>[0];
+type PluginCommandContext = Parameters<RegisterCommandParam["handler"]>[0];
+type PluginCommandResult = Awaited<ReturnType<RegisterCommandParam["handler"]>>;
+
 // ──────────────────────────────────────────────────────────────────────────────
 // Plugin config type
 // ──────────────────────────────────────────────────────────────────────────────
 interface CliPluginConfig {
-  // Phase 1: auth bridge
   codexAuthPath?: string;
   enableCodex?: boolean;
-  // Phase 2: request proxy
   enableProxy?: boolean;
   proxyPort?: number;
   proxyApiKey?: string;
@@ -59,10 +68,53 @@ const DEFAULT_PROXY_PORT = 31337;
 const DEFAULT_PROXY_API_KEY = "cli-bridge";
 
 // ──────────────────────────────────────────────────────────────────────────────
-// Phase 3: slash-command model table
+// State file — persists the model that was active before the last /cli-* switch
+// Located at ~/.openclaw/cli-bridge-state.json (survives gateway restarts)
+// ──────────────────────────────────────────────────────────────────────────────
+const STATE_FILE = join(homedir(), ".openclaw", "cli-bridge-state.json");
+
+interface CliBridgeState {
+  previousModel: string;
+}
+
+function readState(): CliBridgeState | null {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf8")) as CliBridgeState;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state: CliBridgeState): void {
+  try {
+    mkdirSync(join(homedir(), ".openclaw"), { recursive: true });
+    writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + "\n", "utf8");
+  } catch {
+    // non-fatal — /cli-back will just report no previous model
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Read the current primary model from openclaw.json
 // ──────────────────────────────────────────────────────────────────────────────
+function readCurrentModel(): string | null {
+  try {
+    const cfg = JSON.parse(
+      readFileSync(join(homedir(), ".openclaw", "openclaw.json"), "utf8")
+    );
+    const m = cfg?.agents?.defaults?.model;
+    if (typeof m === "string") return m;
+    if (typeof m === "object" && m !== null && typeof m.primary === "string")
+      return m.primary;
+    return null;
+  } catch {
+    return null;
+  }
+}
 
-/** CLI bridge models available via /cli-* slash commands. */
+// ──────────────────────────────────────────────────────────────────────────────
+// Phase 3: model command table
+// ──────────────────────────────────────────────────────────────────────────────
 const CLI_MODEL_COMMANDS = [
   {
     name: "cli-sonnet",
@@ -102,16 +154,24 @@ const CLI_MODEL_COMMANDS = [
   },
 ] as const;
 
+/** Default model used by /cli-test when no arg is given */
+const CLI_TEST_DEFAULT_MODEL = "cli-claude/claude-sonnet-4-6";
+
 // ──────────────────────────────────────────────────────────────────────────────
-// Helper: run `openclaw models set <model>` and return result text
+// Helper: switch global model, saving previous for /cli-back
 // ──────────────────────────────────────────────────────────────────────────────
-
 async function switchModel(
   api: OpenClawPluginApi,
   model: string,
   label: string,
-  _ctx: PluginCommandContext
 ): Promise<PluginCommandResult> {
+  // Save current model BEFORE switching so /cli-back can restore it
+  const current = readCurrentModel();
+  if (current && current !== model) {
+    writeState({ previousModel: current });
+    api.logger.info(`[cli-bridge] saved previous model: ${current}`);
+  }
+
   try {
     const result = await api.runtime.system.runCommandWithTimeout(
       ["openclaw", "models", "set", model],
@@ -126,7 +186,7 @@ async function switchModel(
 
     api.logger.info(`[cli-bridge] switched model → ${model}`);
     return {
-      text: `✅ Switched to ${label}\n\`${model}\``,
+      text: `✅ Switched to **${label}**\n\`${model}\`\n\nUse \`/cli-back\` to restore previous model.`,
     };
   } catch (err) {
     const msg = (err as Error).message;
@@ -135,17 +195,76 @@ async function switchModel(
   }
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Helper: fire a one-shot test request directly at the proxy (no global switch)
+// ──────────────────────────────────────────────────────────────────────────────
+function proxyTestRequest(
+  port: number,
+  apiKey: string,
+  model: string,
+  timeoutMs: number
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      model,
+      messages: [{ role: "user", content: "Reply with exactly: CLI bridge OK" }],
+      stream: false,
+    });
+
+    const req = http.request(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/v1/chat/completions",
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Length": Buffer.byteLength(body),
+        },
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk: Buffer) => { data += chunk.toString(); });
+        res.on("end", () => {
+          try {
+            const parsed = JSON.parse(data) as {
+              choices?: Array<{ message?: { content?: string } }>;
+              error?: { message?: string };
+            };
+            if (parsed.error) {
+              resolve(`Proxy error: ${parsed.error.message}`);
+            } else {
+              resolve(parsed.choices?.[0]?.message?.content?.trim() ?? "(empty response)");
+            }
+          } catch {
+            resolve(`(non-JSON response: ${data.slice(0, 200)})`);
+          }
+        });
+      }
+    );
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error(`Proxy test timed out after ${timeoutMs}ms`));
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
 // ──────────────────────────────────────────────────────────────────────────────
 // Plugin definition
 // ──────────────────────────────────────────────────────────────────────────────
 const plugin = {
   id: "openclaw-cli-bridge-elvatis",
   name: "OpenClaw CLI Bridge",
-  version: "0.2.1",
+  version: "0.2.3",
   description:
-    "Phase 1: openai-codex auth bridge (reads ~/.codex/auth.json). " +
-    "Phase 2: HTTP proxy server routing model calls through gemini/claude CLIs. " +
-    "Phase 3: /cli-* slash commands for instant model switching.",
+    "Phase 1: openai-codex auth bridge. " +
+    "Phase 2: HTTP proxy for gemini/claude CLIs. " +
+    "Phase 3: /cli-* model switching, /cli-back restore, /cli-test health check.",
 
   register(api: OpenClawPluginApi) {
     const cfg = (api.pluginConfig ?? {}) as CliPluginConfig;
@@ -176,7 +295,6 @@ const plugin = {
               try {
                 const creds = await readCodexCredentials(codexAuthPath);
                 spin.stop("Codex CLI credentials loaded");
-
                 return buildOauthProviderAuthResult({
                   providerId: "openai-codex",
                   defaultModel: CODEX_DEFAULT_MODEL,
@@ -212,7 +330,7 @@ const plugin = {
         },
       });
 
-      api.logger.info("[cli-bridge] openai-codex provider registered (Codex CLI auth bridge)");
+      api.logger.info("[cli-bridge] openai-codex provider registered");
     }
 
     // ── Phase 2: CLI request proxy ─────────────────────────────────────────────
@@ -226,47 +344,124 @@ const plugin = {
       })
         .then(() => {
           api.logger.info(
-            `[cli-bridge] proxy ready — vllm/cli-gemini/* and vllm/cli-claude/* available`
+            `[cli-bridge] proxy ready on :${port} — vllm/cli-gemini/* and vllm/cli-claude/* available`
           );
-
-          // Auto-patch openclaw.json with vllm provider config (once)
           const result = patchOpencllawConfig(port);
           if (result.patched) {
             api.logger.info(
-              `[cli-bridge] openclaw.json patched with vllm provider. ` +
-                `Restart gateway to activate cli-gemini/* and cli-claude/* models.`
+              `[cli-bridge] openclaw.json patched with vllm provider. Restart gateway to activate.`
             );
-          } else {
-            api.logger.info(`[cli-bridge] config check: ${result.reason}`);
           }
         })
         .catch((err: Error) => {
-          api.logger.warn(
-            `[cli-bridge] proxy server failed to start on port ${port}: ${err.message}`
-          );
+          api.logger.warn(`[cli-bridge] proxy failed to start on port ${port}: ${err.message}`);
         });
     }
 
-    // ── Phase 3: /cli-* slash commands ────────────────────────────────────────
+    // ── Phase 3a: /cli-* model switch commands ─────────────────────────────────
     for (const entry of CLI_MODEL_COMMANDS) {
-      // Capture entry in closure (const iteration variable is stable in TS/ESM)
       const { name, model, description, label } = entry;
-
       api.registerCommand({
         name,
         description,
-        requireAuth: true, // only authorized senders
+        requireAuth: true,
         handler: async (ctx: PluginCommandContext): Promise<PluginCommandResult> => {
-          api.logger.info(`[cli-bridge] /${name} triggered by ${ctx.senderId ?? "unknown"} (authorized=${ctx.isAuthorizedSender})`);
-          return switchModel(api, model, label, ctx);
+          api.logger.info(`[cli-bridge] /${name} by ${ctx.senderId ?? "?"}`);
+          return switchModel(api, model, label);
         },
-      });
+      } satisfies OpenClawPluginCommandDefinition);
     }
 
-    api.logger.info(
-      `[cli-bridge] registered ${CLI_MODEL_COMMANDS.length} slash commands: ` +
-        CLI_MODEL_COMMANDS.map((c) => `/${c.name}`).join(", ")
-    );
+    // ── Phase 3b: /cli-back — restore previous model ──────────────────────────
+    api.registerCommand({
+      name: "cli-back",
+      description: "Restore the model that was active before the last /cli-* switch",
+      requireAuth: true,
+      handler: async (ctx: PluginCommandContext): Promise<PluginCommandResult> => {
+        api.logger.info(`[cli-bridge] /cli-back by ${ctx.senderId ?? "?"}`);
+
+        const state = readState();
+        if (!state?.previousModel) {
+          return { text: "ℹ️ No previous model saved. Use `/cli-sonnet` etc. to switch first." };
+        }
+
+        const prev = state.previousModel;
+
+        // Clear the saved state so a second /cli-back doesn't bounce back
+        writeState({ previousModel: "" });
+
+        try {
+          const result = await api.runtime.system.runCommandWithTimeout(
+            ["openclaw", "models", "set", prev],
+            { timeoutMs: 8_000 }
+          );
+
+          if (result.code !== 0) {
+            const err = (result.stderr || result.stdout || "unknown error").trim();
+            return { text: `❌ Failed to restore \`${prev}\`: ${err}` };
+          }
+
+          api.logger.info(`[cli-bridge] /cli-back restored → ${prev}`);
+          return { text: `✅ Restored previous model\n\`${prev}\`` };
+        } catch (err) {
+          return { text: `❌ Error: ${(err as Error).message}` };
+        }
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
+    // ── Phase 3c: /cli-test — one-shot proxy ping, no global model switch ──────
+    api.registerCommand({
+      name: "cli-test",
+      description: "Test the CLI bridge proxy without switching your active model. Usage: /cli-test [model]",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: async (ctx: PluginCommandContext): Promise<PluginCommandResult> => {
+        const targetModel = ctx.args?.trim() || CLI_TEST_DEFAULT_MODEL;
+        // Accept short names like "cli-sonnet" or full "vllm/cli-claude/claude-sonnet-4-6"
+        const model = targetModel.startsWith("vllm/")
+          ? targetModel
+          : `vllm/${targetModel}`;
+
+        api.logger.info(`[cli-bridge] /cli-test → ${model} by ${ctx.senderId ?? "?"}`);
+
+        if (!enableProxy) {
+          return { text: "❌ Proxy is disabled (enableProxy: false in config)." };
+        }
+
+        const current = readCurrentModel();
+        const testTimeoutMs = Math.min(timeoutMs, 30_000);
+
+        try {
+          const start = Date.now();
+          const response = await proxyTestRequest(port, apiKey, model, testTimeoutMs);
+          const elapsed = Date.now() - start;
+
+          return {
+            text:
+              `🧪 **CLI Bridge Test**\n` +
+              `Model: \`${model}\`\n` +
+              `Response: _${response}_\n` +
+              `Latency: ${elapsed}ms\n\n` +
+              `Active model unchanged: \`${current ?? "unknown"}\``,
+          };
+        } catch (err) {
+          return {
+            text:
+              `❌ **CLI Bridge Test Failed**\n` +
+              `Model: \`${model}\`\n` +
+              `Error: ${(err as Error).message}\n\n` +
+              `Active model unchanged: \`${current ?? "unknown"}\``,
+          };
+        }
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
+    const allCommands = [
+      ...CLI_MODEL_COMMANDS.map((c) => `/${c.name}`),
+      "/cli-back",
+      "/cli-test",
+    ];
+    api.logger.info(`[cli-bridge] registered ${allCommands.length} commands: ${allCommands.join(", ")}`);
   },
 };
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-cli-bridge-elvatis",
   "name": "OpenClaw CLI Bridge",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
   "providers": [
     "openai-codex"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "scripts": {

package/src/cli-runner.ts

@@ -4,15 +4,16 @@
  * Spawns CLI subprocesses (gemini, claude) and captures their output.
  * Input: OpenAI-format messages → formatted prompt string → CLI stdin.
  *
- * IMPORTANT: Prompt is always passed via stdin (not as a CLI argument) to
- * avoid E2BIG ("Argument list too long") when conversation history is large.
+ * Both Gemini and Claude receive the prompt via stdin to avoid:
+ *   - E2BIG (arg list too long) for large conversation histories
+ *   - Gemini agentic mode (triggered by @file syntax + workspace cwd)
+ *
+ * Gemini is always spawned with cwd = tmpdir() so it doesn't scan the
+ * workspace and enter agentic mode.
  */
 
 import { spawn } from "node:child_process";
-import { writeFileSync, unlinkSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { randomBytes } from "node:crypto";
+import { tmpdir, homedir } from "node:os";
 
 /** Max messages to include in the prompt sent to the CLI. */
 const MAX_MESSAGES = 20;
@@ -31,7 +32,7 @@ export interface ChatMessage {
 /**
  * Convert OpenAI messages to a single flat prompt string.
  * Truncates to MAX_MESSAGES (keeping the most recent) and MAX_MSG_CHARS per
- * message to avoid E2BIG when conversation history is very large.
+ * message to avoid oversized payloads.
  */
 export function formatPrompt(messages: ChatMessage[]): string {
   if (messages.length === 0) return "";
@@ -42,7 +43,7 @@ export function formatPrompt(messages: ChatMessage[]): string {
   const recent = nonSystem.slice(-MAX_MESSAGES);
   const truncated = system ? [system, ...recent] : recent;
 
-  // If single user message with short content, send directly — no wrapping.
+  // Single short user message — send bare (no wrapping needed)
   if (truncated.length === 1 && truncated[0].role === "user") {
     return truncateContent(truncated[0].content);
   }
@@ -51,13 +52,10 @@ export function formatPrompt(messages: ChatMessage[]): string {
     .map((m) => {
       const content = truncateContent(m.content);
       switch (m.role) {
-        case "system":
-          return `[System]\n${content}`;
-        case "assistant":
-          return `[Assistant]\n${content}`;
+        case "system":    return `[System]\n${content}`;
+        case "assistant": return `[Assistant]\n${content}`;
         case "user":
-        default:
-          return `[User]\n${content}`;
+        default:          return `[User]\n${content}`;
       }
     })
     .join("\n\n");
@@ -69,40 +67,26 @@ function truncateContent(s: string): string {
 }
 
 // ──────────────────────────────────────────────────────────────────────────────
-// Core subprocess runner
+// Minimal environment for spawned subprocesses
 // ──────────────────────────────────────────────────────────────────────────────
 
-export interface CliRunResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-
 /**
  * Build a minimal, safe environment for spawning CLI subprocesses.
  *
- * WHY: The OpenClaw gateway may inject large values into process.env at
- * runtime (system prompts, session data, OPENCLAW_* vars, etc.). Spreading
- * the full process.env into spawn() can push the combined argv+envp over
- * ARG_MAX (~2 MB on Linux), causing "spawn E2BIG". Using only the vars that
+ * WHY: The OpenClaw gateway modifies process.env at runtime (OPENCLAW_* vars,
+ * session context, etc.). Spreading the full process.env into spawn() can push
+ * argv+envp over ARG_MAX (~2 MB on Linux) → "spawn E2BIG". Only passing what
  * the CLI tools actually need keeps us well under the limit regardless of
- * what the parent process environment contains.
+ * gateway runtime state.
  */
 function buildMinimalEnv(): Record<string, string> {
-  const pick = (key: string): string | undefined => process.env[key];
-
-  const env: Record<string, string> = {
-    NO_COLOR: "1",
-    TERM: "dumb",
-  };
+  const pick = (key: string) => process.env[key];
+  const env: Record<string, string> = { NO_COLOR: "1", TERM: "dumb" };
 
-  // Essential path/identity vars — always include when present.
   for (const key of ["HOME", "PATH", "USER", "LOGNAME", "SHELL", "TMPDIR", "TMP", "TEMP"]) {
     const v = pick(key);
     if (v) env[key] = v;
   }
-
-  // Allow google-auth / claude auth paths to be inherited.
   for (const key of [
     "GOOGLE_APPLICATION_CREDENTIALS",
     "ANTHROPIC_API_KEY",
@@ -120,37 +104,56 @@ function buildMinimalEnv(): Record<string, string> {
   return env;
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Core subprocess runner
+// ──────────────────────────────────────────────────────────────────────────────
+
+export interface CliRunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface RunCliOptions {
+  /**
+   * Working directory for the subprocess.
+   * Defaults to homedir() — a neutral dir that won't trigger agentic context scanning.
+   */
+  cwd?: string;
+  timeoutMs?: number;
+}
+
 /**
- * Spawn a CLI and deliver the prompt via stdin (not as an argument).
- * This avoids E2BIG ("Argument list too long") for large conversation histories
- * or when the parent process has a large runtime environment.
+ * Spawn a CLI and deliver the prompt via stdin.
+ *
+ * cwd defaults to homedir() so CLIs that scan the working directory for
+ * project context (like Gemini) don't accidentally enter agentic mode.
  */
 export function runCli(
   cmd: string,
   args: string[],
   prompt: string,
-  timeoutMs = 120_000
+  timeoutMs = 120_000,
+  opts: RunCliOptions = {}
 ): Promise<CliRunResult> {
+  const cwd = opts.cwd ?? homedir();
+
   return new Promise((resolve, reject) => {
     const proc = spawn(cmd, args, {
       timeout: timeoutMs,
       env: buildMinimalEnv(),
+      cwd,
     });
 
     let stdout = "";
     let stderr = "";
 
-    // Write prompt to stdin then close — prevents the CLI from waiting for more input.
     proc.stdin.write(prompt, "utf8", () => {
       proc.stdin.end();
     });
 
-    proc.stdout.on("data", (d: Buffer) => {
-      stdout += d.toString();
-    });
-    proc.stderr.on("data", (d: Buffer) => {
-      stderr += d.toString();
-    });
+    proc.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+    proc.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
 
     proc.on("close", (code) => {
       resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0 });
@@ -167,8 +170,19 @@ export function runCli(
 // ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * Run: gemini -m <modelId> -p "<prompt>"
- * Strips the model prefix ("cli-gemini/gemini-2.5-pro" → "gemini-2.5-pro").
+ * Run Gemini CLI in headless mode with prompt delivered via stdin.
+ *
+ * WHY stdin (not @file):
+ *   The @file syntax (`gemini -p @/tmp/xxx.txt`) triggers Gemini's agentic
+ *   mode — it scans the current working directory for project context and
+ *   interprets the prompt as a task instruction, not a Q&A. This causes hangs,
+ *   wrong answers, and "directory does not exist" errors when run from a
+ *   project workspace.
+ *
+ * Gemini CLI: -p "" triggers headless mode; stdin content is the actual prompt
+ * (per Gemini docs: "prompt is appended to input on stdin (if any)").
+ *
+ * cwd = tmpdir() — neutral empty-ish dir, prevents workspace context scanning.
  */
 export async function runGemini(
   prompt: string,
@@ -176,24 +190,22 @@ export async function runGemini(
   timeoutMs: number
 ): Promise<string> {
   const model = stripPrefix(modelId);
-  // Gemini CLI doesn't support stdin — write prompt to a temp file and read it via @file syntax
-  const tmpFile = join(tmpdir(), `cli-bridge-${randomBytes(6).toString("hex")}.txt`);
-  writeFileSync(tmpFile, prompt, "utf8");
-  try {
-    // Use @<file> to pass prompt from file (avoids ARG_MAX limit)
-    const args = ["-m", model, "-p", `@${tmpFile}`];
-    const result = await runCli("gemini", args, "", timeoutMs);
-
-    if (result.exitCode !== 0 && result.stdout.length === 0) {
-      throw new Error(
-        `gemini exited ${result.exitCode}: ${result.stderr || "(no output)"}`
-      );
-    }
-
-    return result.stdout || result.stderr;
-  } finally {
-    try { unlinkSync(tmpFile); } catch { /* ignore */ }
+  // -p "" = headless mode trigger; actual prompt arrives via stdin
+  const args = ["-m", model, "-p", ""];
+  const result = await runCli("gemini", args, prompt, timeoutMs, { cwd: tmpdir() });
+
+  // Filter out [WARN] lines from stderr (Gemini emits noisy permission warnings)
+  const cleanStderr = result.stderr
+    .split("\n")
+    .filter((l) => !l.startsWith("[WARN]") && !l.startsWith("Loaded cached"))
+    .join("\n")
+    .trim();
+
+  if (result.exitCode !== 0 && result.stdout.length === 0) {
+    throw new Error(`gemini exited ${result.exitCode}: ${cleanStderr || "(no output)"}`);
   }
+
+  return result.stdout || cleanStderr;
 }
 
 // ──────────────────────────────────────────────────────────────────────────────
@@ -201,7 +213,7 @@ export async function runGemini(
 // ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * Run: claude -p --output-format text -m <modelId> "<prompt>"
+ * Run Claude Code CLI in headless mode with prompt delivered via stdin.
  * Strips the model prefix ("cli-claude/claude-opus-4-6" → "claude-opus-4-6").
  */
 export async function runClaude(
@@ -210,24 +222,17 @@ export async function runClaude(
   timeoutMs: number
 ): Promise<string> {
   const model = stripPrefix(modelId);
-  // No prompt argument — deliver via stdin to avoid E2BIG
   const args = [
     "-p",
-    "--output-format",
-    "text",
-    "--permission-mode",
-    "plan",
-    "--tools",
-    "",
-    "--model",
-    model,
+    "--output-format", "text",
+    "--permission-mode", "plan",
+    "--tools", "",
+    "--model", model,
   ];
   const result = await runCli("claude", args, prompt, timeoutMs);
 
   if (result.exitCode !== 0 && result.stdout.length === 0) {
-    throw new Error(
-      `claude exited ${result.exitCode}: ${result.stderr || "(no output)"}`
-    );
+    throw new Error(`claude exited ${result.exitCode}: ${result.stderr || "(no output)"}`);
   }
 
   return result.stdout;
@@ -238,8 +243,7 @@ export async function runClaude(
 // ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * Route a chat completion request to the right CLI based on the model name.
- * Model naming convention:
+ * Route a chat completion to the correct CLI based on model prefix.
  *   cli-gemini/<id>  → gemini CLI
  *   cli-claude/<id>  → claude CLI
  */
@@ -250,17 +254,11 @@ export async function routeToCliRunner(
 ): Promise<string> {
   const prompt = formatPrompt(messages);
 
-  if (model.startsWith("cli-gemini/")) {
-    return runGemini(prompt, model, timeoutMs);
-  }
-
-  if (model.startsWith("cli-claude/")) {
-    return runClaude(prompt, model, timeoutMs);
-  }
+  if (model.startsWith("cli-gemini/")) return runGemini(prompt, model, timeoutMs);
+  if (model.startsWith("cli-claude/")) return runClaude(prompt, model, timeoutMs);
 
   throw new Error(
-    `Unknown CLI bridge model: "${model}". ` +
-      `Use "cli-gemini/<model>" or "cli-claude/<model>".`
+    `Unknown CLI bridge model: "${model}". Use "cli-gemini/<model>" or "cli-claude/<model>".`
   );
 }
 
@@ -268,7 +266,6 @@ export async function routeToCliRunner(
 // Helpers
 // ──────────────────────────────────────────────────────────────────────────────
 
-/** Strip the "cli-gemini/" or "cli-claude/" prefix from a model ID. */
 function stripPrefix(modelId: string): string {
   const slash = modelId.indexOf("/");
   return slash === -1 ? modelId : modelId.slice(slash + 1);