Merge pull request #109 from JerrettDavis/feat/openclaw-upstream-gateway

README.md

@@ -135,6 +135,7 @@ headroom wrap codex        # Starts proxy + launches OpenAI Codex CLI
 headroom wrap aider        # Starts proxy + launches Aider
 headroom wrap cursor       # Starts proxy + prints Cursor config
 headroom wrap openclaw     # Installs + configures OpenClaw plugin
+headroom unwrap openclaw   # Disables plugin + restores legacy engine
 ```
 
 Headroom starts a proxy, points your tool at it, and compresses everything automatically.
@@ -174,7 +175,7 @@ Gives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `h
 | **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |
 | **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` |
 | **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` |
-| **OpenClaw** | One-command wrap | `headroom wrap openclaw` |
+| **OpenClaw** | One-command wrap/unwrap | `headroom wrap openclaw` / `headroom unwrap openclaw` |
 | **Claude Code** | Wrap | `headroom wrap claude` |
 | **Codex / Aider** | Wrap | `headroom wrap codex` or `headroom wrap aider` |
 

e2e/wrap/run.py

@@ -355,6 +355,11 @@ def start_openclaw_gateway(env: dict[str, str], cwd: Path) -> subprocess.Popen[s
     )
 
 
+def stop_openclaw_gateway(env: dict[str, str], cwd: Path) -> None:
+    log("Stopping OpenClaw gateway after e2e verification")
+    run(["openclaw", "gateway", "stop"], env=env, cwd=cwd, timeout=60)
+
+
 def verify_installs() -> None:
     log("Verifying installed packages and binaries")
     for tool in ("headroom", "codex", "aider", "openclaw"):
@@ -617,6 +622,7 @@ def verify_openclaw_wrap(
     finally:
         if gateway_proc is not None:
             stop_process(gateway_proc)
+        stop_openclaw_gateway(base_env, project_dir)
 
 
 def main() -> None:

headroom/cli/proxy.py

@@ -35,6 +35,18 @@ from .main import main
 @click.option("--no-optimize", is_flag=True, help="Disable optimization (passthrough mode)")
 @click.option("--no-cache", is_flag=True, help="Disable semantic caching")
 @click.option("--no-rate-limit", is_flag=True, help="Disable rate limiting")
+@click.option(
+    "--retry-max-attempts",
+    type=int,
+    default=None,
+    help="Maximum upstream retry attempts for connect/read/5xx failures (default: 3)",
+)
+@click.option(
+    "--connect-timeout-seconds",
+    type=int,
+    default=None,
+    help="Upstream connection timeout in seconds (default: 10)",
+)
 @click.option("--log-file", default=None, help="Path to JSONL log file")
 @click.option("--budget", type=float, default=None, help="Daily budget limit in USD")
 # Code-aware compression (ON by default if installed)
@@ -154,6 +166,8 @@ def proxy(
     no_optimize: bool,
     no_cache: bool,
     no_rate_limit: bool,
+    retry_max_attempts: int | None,
+    connect_timeout_seconds: int | None,
     log_file: str | None,
     budget: float | None,
     no_code_aware: bool,
@@ -232,6 +246,10 @@ def proxy(
         optimize=not no_optimize,
         cache_enabled=not no_cache,
         rate_limit_enabled=not no_rate_limit,
+        retry_max_attempts=retry_max_attempts if retry_max_attempts is not None else 3,
+        connect_timeout_seconds=connect_timeout_seconds
+        if connect_timeout_seconds is not None
+        else 10,
         log_file=log_file,
         budget_limit_usd=budget,
         # Code-aware: ON by default (use --no-code-aware to disable)

headroom/cli/wrap.py

@@ -478,6 +478,131 @@ def _resolve_openclaw_extensions_dir(openclaw_bin: str) -> Path:
     return config_path.parent / "extensions"
 
 
+def _normalize_openclaw_gateway_provider_ids(provider_ids: tuple[str, ...] | None) -> list[str]:
+    """Normalize configured OpenClaw provider ids, defaulting to openai-codex."""
+    values = provider_ids or ()
+    seen: set[str] = set()
+    normalized: list[str] = []
+
+    for entry in values:
+        provider_id = entry.strip()
+        if not provider_id or provider_id in seen:
+            continue
+        seen.add(provider_id)
+        normalized.append(provider_id)
+
+    if normalized:
+        return normalized
+    return ["openai-codex"]
+
+
+def _read_openclaw_config_value(openclaw_bin: str, path: str) -> Any | None:
+    """Read an OpenClaw config value when present, returning None on missing paths."""
+    result = subprocess.run(
+        [openclaw_bin, "config", "get", path],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        return None
+
+    output = result.stdout.strip()
+    if not output:
+        return None
+
+    try:
+        return json.loads(output)
+    except json.JSONDecodeError:
+        return output
+
+
+def _build_openclaw_plugin_entry(
+    *,
+    existing_entry: Any,
+    proxy_port: int,
+    startup_timeout_ms: int,
+    python_path: str | None,
+    no_auto_start: bool,
+    gateway_provider_ids: tuple[str, ...] | None,
+    enabled: bool,
+) -> dict[str, object]:
+    """Merge managed Headroom plugin settings with any existing entry payload."""
+    base_entry = existing_entry if isinstance(existing_entry, dict) else {}
+    existing_config = base_entry.get("config")
+    next_config = dict(existing_config) if isinstance(existing_config, dict) else {}
+
+    next_config["proxyPort"] = proxy_port
+    next_config["autoStart"] = not no_auto_start
+    next_config["startupTimeoutMs"] = startup_timeout_ms
+    next_config["gatewayProviderIds"] = _normalize_openclaw_gateway_provider_ids(
+        gateway_provider_ids
+    )
+
+    if python_path:
+        next_config["pythonPath"] = python_path
+    else:
+        next_config.pop("pythonPath", None)
+
+    return {
+        **base_entry,
+        "enabled": enabled,
+        "config": next_config,
+    }
+
+
+def _write_openclaw_plugin_entry(openclaw_bin: str, entry: dict[str, object]) -> None:
+    """Persist the Headroom plugin config entry."""
+    _run_checked(
+        [
+            openclaw_bin,
+            "config",
+            "set",
+            "plugins.entries.headroom",
+            json.dumps(entry, separators=(",", ":")),
+            "--strict-json",
+        ],
+        action="openclaw config set plugins.entries.headroom",
+    )
+
+
+def _set_openclaw_context_engine_slot(openclaw_bin: str, engine_id: str) -> None:
+    """Persist the selected OpenClaw context engine slot."""
+    _run_checked(
+        [
+            openclaw_bin,
+            "config",
+            "set",
+            "plugins.slots.contextEngine",
+            json.dumps(engine_id),
+            "--strict-json",
+        ],
+        action="openclaw config set plugins.slots.contextEngine",
+    )
+
+
+def _restart_or_start_openclaw_gateway(openclaw_bin: str) -> tuple[str, str]:
+    """Restart the gateway when running, otherwise start it."""
+    restart_result = subprocess.run(
+        [openclaw_bin, "gateway", "restart"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if restart_result.returncode == 0:
+        output = restart_result.stdout.strip() or restart_result.stderr.strip()
+        return "restarted", output
+
+    start_result = _run_checked(
+        [openclaw_bin, "gateway", "start"],
+        action="openclaw gateway start",
+    )
+    output = start_result.stdout.strip() or start_result.stderr.strip()
+    return "started", output
+
+
 def _copy_openclaw_plugin_into_extensions(
     *,
     plugin_dir: Path,
@@ -533,6 +658,11 @@ def wrap() -> None:
     """
 
 
+@main.group()
+def unwrap() -> None:
+    """Undo durable Headroom wrapping for supported tools."""
+
+
 # =============================================================================
 # Claude Code
 # =============================================================================
@@ -913,6 +1043,12 @@ def cursor(port: int, no_rtk: bool, no_proxy: bool, learn: bool, verbose: bool)
 )
 @click.option("--proxy-port", default=8787, type=int, help="Headroom proxy port")
 @click.option("--startup-timeout-ms", default=20000, type=int, help="Proxy startup timeout")
+@click.option(
+    "--gateway-provider-id",
+    "gateway_provider_ids",
+    multiple=True,
+    help="OpenClaw provider id to route through Headroom (repeatable; default: openai-codex)",
+)
 @click.option(
     "--python-path",
     default=None,
@@ -936,6 +1072,7 @@ def openclaw(
     copy: bool,
     proxy_port: int,
     startup_timeout_ms: int,
+    gateway_provider_ids: tuple[str, ...],
     python_path: str | None,
     no_auto_start: bool,
     no_restart: bool,
@@ -995,6 +1132,24 @@ def openclaw(
     elif not local_source_mode and skip_build:
         click.echo("  Skipping build: npm install mode does not build local source.")
 
+    effective_python_path = python_path
+    if effective_python_path is None and not no_auto_start and sys.executable:
+        effective_python_path = sys.executable
+
+    existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")
+    entry = _build_openclaw_plugin_entry(
+        existing_entry=existing_entry,
+        proxy_port=proxy_port,
+        startup_timeout_ms=startup_timeout_ms,
+        python_path=effective_python_path,
+        no_auto_start=no_auto_start,
+        gateway_provider_ids=gateway_provider_ids,
+        enabled=True,
+    )
+
+    click.echo("  Writing plugin configuration...")
+    _write_openclaw_plugin_entry(openclaw_bin, entry)
+
     install_cmd = [
         openclaw_bin,
         "plugins",
@@ -1047,38 +1202,7 @@ def openclaw(
     elif verbose and install_result.stdout.strip():
         click.echo(install_result.stdout.strip())
 
-    plugin_config: dict[str, object] = {
-        "proxyPort": proxy_port,
-        "autoStart": not no_auto_start,
-        "startupTimeoutMs": startup_timeout_ms,
-    }
-    if python_path:
-        plugin_config["pythonPath"] = python_path
-    entry = {"enabled": True, "config": plugin_config}
-
-    click.echo("  Writing plugin configuration...")
-    _run_checked(
-        [
-            openclaw_bin,
-            "config",
-            "set",
-            "plugins.entries.headroom",
-            json.dumps(entry, separators=(",", ":")),
-            "--strict-json",
-        ],
-        action="openclaw config set plugins.entries.headroom",
-    )
-    _run_checked(
-        [
-            openclaw_bin,
-            "config",
-            "set",
-            "plugins.slots.contextEngine",
-            json.dumps("headroom"),
-            "--strict-json",
-        ],
-        action="openclaw config set plugins.slots.contextEngine",
-    )
+    _set_openclaw_context_engine_slot(openclaw_bin, "headroom")
     _run_checked(
         [openclaw_bin, "config", "validate"],
         action="openclaw config validate",
@@ -1086,15 +1210,15 @@ def openclaw(
 
     if no_restart:
         click.echo("  Skipping gateway restart (--no-restart).")
-        click.echo("  Run `openclaw gateway restart` to apply plugin changes.")
-    else:
-        click.echo("  Warning: restarting OpenClaw gateway to apply plugin changes.")
-        restart_result = _run_checked(
-            [openclaw_bin, "gateway", "restart"],
-            action="openclaw gateway restart",
+        click.echo(
+            "  Run `openclaw gateway restart` (or `openclaw gateway start`) to apply plugin changes."
         )
-        if verbose and restart_result.stdout.strip():
-            click.echo(restart_result.stdout.strip())
+    else:
+        click.echo("  Applying plugin changes to OpenClaw gateway...")
+        gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)
+        click.echo(f"  Gateway {gateway_action}.")
+        if verbose and gateway_output:
+            click.echo(gateway_output)
 
     inspect_result = _run_checked(
         [openclaw_bin, "plugins", "inspect", "headroom"],
@@ -1108,3 +1232,71 @@ def openclaw(
     click.echo("  Plugin: headroom")
     click.echo("  Slot:   plugins.slots.contextEngine = headroom")
     click.echo()
+
+
+@unwrap.command("openclaw")
+@click.option("--no-restart", is_flag=True, help="Do not restart OpenClaw gateway at the end")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+def unwrap_openclaw(no_restart: bool, verbose: bool) -> None:
+    """Disable the Headroom OpenClaw plugin and restore the legacy engine slot."""
+    openclaw_bin = shutil.which("openclaw")
+    if not openclaw_bin:
+        raise click.ClickException("'openclaw' not found in PATH. Install OpenClaw CLI first.")
+
+    click.echo()
+    click.echo("  ╔═══════════════════════════════════════════════╗")
+    click.echo("  ║          HEADROOM UNWRAP: OPENCLAW            ║")
+    click.echo("  ╚═══════════════════════════════════════════════╝")
+    click.echo()
+    click.echo("  Disabling Headroom plugin and removing engine mapping...")
+
+    existing_entry = _read_openclaw_config_value(openclaw_bin, "plugins.entries.headroom")
+    existing_config = {}
+    if isinstance(existing_entry, dict) and isinstance(existing_entry.get("config"), dict):
+        existing_config = {
+            key: value
+            for key, value in existing_entry["config"].items()
+            if key
+            not in {
+                "gatewayProviderIds",
+                "proxyUrl",
+                "proxyPort",
+                "autoStart",
+                "startupTimeoutMs",
+                "pythonPath",
+            }
+        }
+
+    entry = {"enabled": False, "config": existing_config}
+    _write_openclaw_plugin_entry(openclaw_bin, entry)
+    _set_openclaw_context_engine_slot(openclaw_bin, "legacy")
+    _run_checked(
+        [openclaw_bin, "config", "validate"],
+        action="openclaw config validate",
+    )
+
+    if no_restart:
+        click.echo("  Skipping gateway restart (--no-restart).")
+        click.echo(
+            "  Run `openclaw gateway restart` (or `openclaw gateway start`) to apply unwrap changes."
+        )
+    else:
+        click.echo("  Applying unwrap changes to OpenClaw gateway...")
+        gateway_action, gateway_output = _restart_or_start_openclaw_gateway(openclaw_bin)
+        click.echo(f"  Gateway {gateway_action}.")
+        if verbose and gateway_output:
+            click.echo(gateway_output)
+
+    if verbose:
+        inspect_result = _run_checked(
+            [openclaw_bin, "plugins", "inspect", "headroom"],
+            action="openclaw plugins inspect headroom",
+        )
+        if inspect_result.stdout.strip():
+            click.echo(inspect_result.stdout.strip())
+
+    click.echo()
+    click.echo("✓ OpenClaw Headroom wrap removed.")
+    click.echo("  Plugin: headroom (installed, disabled)")
+    click.echo("  Slot:   plugins.slots.contextEngine = legacy")
+    click.echo()

headroom/proxy/handlers/openai.py

@@ -6,6 +6,7 @@ Contains all OpenAI Chat Completions, Responses API, and passthrough handlers.
 from __future__ import annotations
 
 import asyncio
+import base64
 import contextlib
 import copy
 import json
@@ -24,6 +25,51 @@ if TYPE_CHECKING:
 logger = logging.getLogger("headroom.proxy")
 
 
+def _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:
+    """Best-effort decode of an OpenAI OAuth bearer token payload.
+
+    OpenClaw's Codex OAuth flow may forward only the bearer token after the
+    provider base URL is overridden. In that case the explicit
+    ``ChatGPT-Account-ID`` header can be missing even though the JWT still
+    carries the account id we need to route to the ChatGPT Codex backend.
+    """
+    auth = headers.get("authorization") or headers.get("Authorization")
+    if not auth:
+        return None
+
+    scheme, _, token = auth.partition(" ")
+    if scheme.lower() != "bearer" or token.count(".") < 2:
+        return None
+
+    payload = token.split(".", 2)[1]
+    payload += "=" * (-len(payload) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(payload.encode("ascii"))
+        data = json.loads(decoded.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+
+    return data if isinstance(data, dict) else None
+
+
+def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, str], bool]:
+    """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""
+    resolved = dict(headers)
+    lower_lookup = {k.lower(): k for k in resolved}
+
+    if "chatgpt-account-id" in lower_lookup:
+        return resolved, True
+
+    payload = _decode_openai_bearer_payload(resolved)
+    auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None
+    account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None
+    if isinstance(account_id, str) and account_id.strip():
+        resolved["ChatGPT-Account-ID"] = account_id.strip()
+        return resolved, True
+
+    return resolved, False
+
+
 class OpenAIHandlerMixin:
     """Mixin providing OpenAI API handler methods for HeadroomProxy."""
 
@@ -836,9 +882,11 @@ class OpenAIHandlerMixin:
                 f"(backend '{self.anthropic_backend.name}' not used for Responses API)"
             )
 
+        headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
+
         # Route to correct endpoint based on auth mode.
         # ChatGPT session auth (codex login) uses chatgpt.com, not api.openai.com.
-        if headers.get("chatgpt-account-id"):
+        if is_chatgpt_auth:
             url = "https://chatgpt.com/backend-api/codex/responses"
         else:
             url = f"{self.OPENAI_API_URL}/v1/responses"
@@ -983,11 +1031,8 @@ class OpenAIHandlerMixin:
             if k.lower() not in _skip_headers:
                 upstream_headers[k] = v
 
-        # Detect ChatGPT session auth vs API key auth.
-        # Codex sends `ChatGPT-Account-ID` header when using `codex login`
-        # (ChatGPT OAuth), which requires routing to chatgpt.com, not api.openai.com.
+        upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)
         _lower_headers = {k.lower(): v for k, v in upstream_headers.items()}
-        is_chatgpt_auth = "chatgpt-account-id" in _lower_headers
 
         # Build upstream WebSocket URL based on auth mode
         if is_chatgpt_auth:

headroom/proxy/server.py

@@ -1747,6 +1747,16 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
         """OpenAI Responses API (new API introduced March 2025)."""
         return await proxy.handle_openai_responses(request)
 
+    @app.post("/backend-api/responses")
+    async def openai_codex_responses(request: Request):
+        """OpenAI Codex Responses API path preserved from ChatGPT backend."""
+        return await proxy.handle_openai_responses(request)
+
+    @app.post("/backend-api/codex/responses")
+    async def openai_codex_nested_responses(request: Request):
+        """OpenAI Codex Responses API path for codex-shaped proxy base URLs."""
+        return await proxy.handle_openai_responses(request)
+
     @app.websocket("/v1/responses")
     async def openai_responses_ws(websocket: WebSocket):
         """OpenAI Responses API via WebSocket (Codex gpt-5.4+)."""
@@ -1793,6 +1803,28 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
             logger.error(f"Passthrough /v1/responses/{sub_path} failed: {e}")
             return Response(content=str(e), status_code=502)
 
+    @app.websocket("/backend-api/responses")
+    async def openai_codex_responses_ws(websocket: WebSocket):
+        """OpenAI Codex Responses WebSocket path preserved from ChatGPT backend."""
+        await proxy.handle_openai_responses_ws(websocket)
+
+    @app.websocket("/backend-api/codex/responses")
+    async def openai_codex_nested_responses_ws(websocket: WebSocket):
+        """OpenAI Codex Responses WebSocket path for codex-shaped proxy base URLs."""
+        await proxy.handle_openai_responses_ws(websocket)
+
+    @app.api_route("/backend-api/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])
+    async def openai_codex_responses_sub(request: Request, sub_path: str):
+        """Passthrough for /backend-api/responses/* sub-endpoints."""
+        return await openai_responses_sub(request, sub_path)
+
+    @app.api_route(
+        "/backend-api/codex/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"]
+    )
+    async def openai_codex_nested_responses_sub(request: Request, sub_path: str):
+        """Passthrough for /backend-api/codex/responses/* sub-endpoints."""
+        return await openai_responses_sub(request, sub_path)
+
     # OpenAI Batch API endpoints (with compression!)
     @app.post("/v1/batches")
     async def create_batch(request: Request):

plugins/openclaw/README.md

@@ -79,6 +79,67 @@ Install automatically selects the `contextEngine` slot for `headroom` on current
 
 Default `proxyPort` is `8787`.
 
+### Upstream gateway routing
+
+By default, the plugin also rewrites the built-in `openai-codex` provider base URL to the active Headroom proxy at runtime. That means Codex provider traffic flows through Headroom, so `/stats` can observe real upstream request and cache activity instead of only local context compression.
+
+This does not replace Headroom's existing Codex routing rules. The proxy already decides between `api.openai.com` and `chatgpt.com/backend-api/codex/responses` based on ChatGPT auth. The plugin change only points OpenClaw's provider config at the active proxy in memory and preserves the rest of the provider config.
+
+You can also route additional provider ids such as `anthropic`, `github-copilot`, `google`, or `openrouter` through the same proxy:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "gatewayProviderIds": ["openai-codex", "anthropic", "github-copilot", "google", "openrouter"]
+        }
+      }
+    }
+  }
+}
+```
+
+When `gatewayProviderIds` is set, it becomes the exact list the plugin rewrites in memory for the current gateway process.
+
+For convenience, the plugin also accepts family aliases:
+- `codex` -> `openai-codex`
+- `claude` -> `anthropic`
+- `copilot` -> `github-copilot`
+- `gemini` -> `google`
+
+When OpenClaw has already resolved a provider's upstream `baseUrl`, the plugin preserves protocol-specific path segments while swapping only the origin. That keeps provider families on the right proxy route:
+- Codex / ChatGPT backend: `/backend-api`
+- OpenAI-compatible providers: `/v1` or `/api/v1`
+- GitHub Copilot Claude-family models: `/anthropic`
+- Gemini: `/v1beta`
+
+GitHub Copilot is a special case because OpenClaw can route it through either OpenAI Responses or Anthropic Messages depending on the selected model. The plugin only rewrites Copilot when OpenClaw has already resolved the upstream `baseUrl`, so it can preserve the correct `/v1` or `/anthropic` path instead of guessing.
+
+The routing is intentionally lightweight and reversible:
+- the plugin does not persist provider `baseUrl` changes back to `openclaw.json`
+- disabling the plugin, clearing `gatewayProviderIds`, or restarting without Headroom restores OpenClaw's normal provider resolution
+- if you want durable provider rewrites, use `headroom wrap openclaw` instead of relying on plugin install side effects
+
+If you need to disable that behavior:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "headroom": {
+        "enabled": true,
+        "config": {
+          "routeCodexViaProxy": false
+        }
+      }
+    }
+  }
+}
+```
+
 ### Local proxy (auto-start)
 
 When `proxyUrl` points to localhost (or is omitted), the plugin will auto-start `headroom proxy` if no running proxy is detected. Launch order:
@@ -141,6 +202,8 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored
 | `pythonPath` | auto-detected | Optional Python executable override for Python fallback launcher. |
 | `autoStart` | `true` | Auto-start a local `headroom proxy` if not already running (local URLs only; ignored for remote proxies) |
 | `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
+| `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. |
+| `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |
 
 ## Comparison with lossless-claw
 

plugins/openclaw/openclaw.plugin.json

@@ -13,6 +13,22 @@
     "pythonPath": {
       "label": "Python Path",
       "help": "Optional explicit python executable for python fallback launcher (for example: python, python3, py, or full path)."
+    },
+    "retryMaxAttempts": {
+      "label": "Retry Max Attempts",
+      "help": "Optional maximum number of upstream retry attempts for connection/read/5xx failures when the plugin auto-starts a local Headroom proxy. Lower values fail faster for interactive chat."
+    },
+    "connectTimeoutSeconds": {
+      "label": "Connect Timeout Seconds",
+      "help": "Optional upstream connection timeout for the auto-started local Headroom proxy. Lower values surface network failures sooner."
+    },
+    "routeCodexViaProxy": {
+      "label": "Route OpenAI Codex Via Headroom",
+      "help": "When enabled, OpenClaw will use the active Headroom proxy as the in-memory upstream base URL for the built-in openai-codex provider so provider traffic flows through Headroom."
+    },
+    "gatewayProviderIds": {
+      "label": "Gateway Provider IDs",
+      "help": "Optional list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases codex, claude, copilot, and gemini are also accepted. When set, this overrides the default openai-codex-only routing."
     }
   },
   "configSchema": {
@@ -44,6 +60,25 @@
         "minimum": 1000,
         "maximum": 120000,
         "default": 20000
+      },
+      "retryMaxAttempts": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "connectTimeoutSeconds": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "routeCodexViaProxy": {
+        "type": "boolean",
+        "default": true
+      },
+      "gatewayProviderIds": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "default": []
       }
     }
   },

plugins/openclaw/src/engine.ts

@@ -27,6 +27,8 @@ export class HeadroomContextEngine {
   private proxyUrl: string | null = null;
   private config: HeadroomEngineConfig;
   private logger: ProxyManagerLogger;
+  private proxyReadyListeners = new Set<(proxyUrl: string) => void | Promise<void>>();
+  private proxyStartupPromise: Promise<string> | null = null;
   private stats = {
     totalCompressions: 0,
     totalTokensSaved: 0,
@@ -51,14 +53,8 @@ export class HeadroomContextEngine {
       return { bootstrapped: false, reason: "disabled" };
     }
 
-    try {
-      this.proxyUrl = await this.proxyManager.start();
-      this.logger.info(`Engine bootstrapped (proxy: ${this.proxyUrl})`);
-      return { bootstrapped: true };
-    } catch (error) {
-      this.logger.error(`Bootstrap failed: ${error}`);
-      return { bootstrapped: false, reason: String(error) };
-    }
+    this.ensureProxyStarted();
+    return { bootstrapped: true, reason: "proxy startup scheduled" };
   }
 
   async ingest(params: {
@@ -95,6 +91,7 @@ export class HeadroomContextEngine {
     systemPromptAddition?: string;
   }> {
     if (!this.proxyUrl || this.config.enabled === false) {
+      this.ensureProxyStarted();
       // Fallback: return messages unchanged
       return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };
     }
@@ -237,4 +234,51 @@ export class HeadroomContextEngine {
   getProxyUrl(): string | null {
     return this.proxyUrl;
   }
+
+  ensureProxyStarted(): void {
+    if (this.config.enabled === false || this.proxyUrl || this.proxyStartupPromise) {
+      return;
+    }
+
+    this.proxyStartupPromise = this.proxyManager
+      .start()
+      .then(async (proxyUrl) => {
+        this.proxyUrl = proxyUrl;
+        await this.notifyProxyReady(proxyUrl);
+        this.logger.info(`Headroom proxy ready at ${proxyUrl}`);
+        return proxyUrl;
+      })
+      .catch((error) => {
+        this.logger.warn(`Headroom proxy unavailable: ${error}`);
+        throw error;
+      })
+      .finally(() => {
+        this.proxyStartupPromise = null;
+      });
+  }
+
+  onProxyReady(listener: (proxyUrl: string) => void | Promise<void>): () => void {
+    this.proxyReadyListeners.add(listener);
+    return () => {
+      this.proxyReadyListeners.delete(listener);
+    };
+  }
+
+  async ensureProxyUrl(): Promise<string> {
+    if (this.proxyUrl) {
+      return this.proxyUrl;
+    }
+
+    this.ensureProxyStarted();
+    if (!this.proxyStartupPromise) {
+      throw new Error("Headroom proxy startup is disabled");
+    }
+    return this.proxyStartupPromise;
+  }
+
+  private async notifyProxyReady(proxyUrl: string): Promise<void> {
+    for (const listener of this.proxyReadyListeners) {
+      await listener(proxyUrl);
+    }
+  }
 }

plugins/openclaw/src/gateway-config.ts

@@ -0,0 +1,143 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export const DEFAULT_GATEWAY_PROVIDER_IDS = ["openai-codex"] as const;
+
+const DEFAULT_PROVIDER_BASE_URLS: Readonly<Record<string, string>> = {
+  "openai-codex": "https://chatgpt.com/backend-api",
+};
+
+const GATEWAY_PROVIDER_ID_ALIASES: Readonly<Record<string, string>> = {
+  codex: "openai-codex",
+  claude: "anthropic",
+  copilot: "github-copilot",
+  gemini: "google",
+};
+
+const EXPLICIT_BASE_URL_REQUIRED_PROVIDER_IDS = new Set<string>(["github-copilot"]);
+
+export function resolveGatewayProviderIds(config: Record<string, unknown> | undefined): string[] {
+  const configuredProviderIds = normalizeGatewayProviderIds(config?.gatewayProviderIds);
+  if (configuredProviderIds.length > 0) {
+    return configuredProviderIds;
+  }
+
+  if (config?.routeCodexViaProxy === false) {
+    return [];
+  }
+
+  return [...DEFAULT_GATEWAY_PROVIDER_IDS];
+}
+
+function normalizeGatewayProviderIds(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+
+  for (const entry of value) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+
+    const rawProviderId = entry.trim();
+    const providerId = GATEWAY_PROVIDER_ID_ALIASES[rawProviderId.toLowerCase()] ?? rawProviderId;
+    if (!providerId || seen.has(providerId)) {
+      continue;
+    }
+
+    seen.add(providerId);
+    normalized.push(providerId);
+  }
+
+  return normalized;
+}
+
+export function applyGatewayProviderBaseUrls<T>(
+  cfg: T,
+  proxyUrl: string,
+  providerIds: readonly string[],
+): { changed: boolean; config: T } {
+  const next = structuredClone((cfg ?? {}) as any);
+  const changed = applyGatewayProviderBaseUrlsInPlace(next, proxyUrl, providerIds);
+  return { changed, config: next as T };
+}
+
+export function applyGatewayProviderBaseUrlsInPlace(
+  cfg: any,
+  proxyUrl: string,
+  providerIds: readonly string[],
+): boolean {
+  if (!cfg || typeof cfg !== "object" || providerIds.length === 0) {
+    return false;
+  }
+
+  const models = (cfg.models ??= {});
+  const providers = (models.providers ??= {});
+  let changed = false;
+
+  for (const providerId of providerIds) {
+    const currentValue = providers[providerId];
+    const currentConfig =
+      currentValue && typeof currentValue === "object" && !Array.isArray(currentValue)
+        ? currentValue
+        : {};
+    const nextConfig = { ...currentConfig };
+    const currentBaseUrl =
+      typeof nextConfig.baseUrl === "string" && nextConfig.baseUrl.trim().length > 0
+        ? nextConfig.baseUrl
+        : undefined;
+    const defaultBaseUrl = DEFAULT_PROVIDER_BASE_URLS[providerId];
+    if (
+      !currentBaseUrl &&
+      !defaultBaseUrl &&
+      EXPLICIT_BASE_URL_REQUIRED_PROVIDER_IDS.has(providerId)
+    ) {
+      continue;
+    }
+    const nextBaseUrl = routeBaseUrlThroughProxy({
+      providerId,
+      proxyUrl,
+      currentBaseUrl,
+    });
+
+    if (!Array.isArray(nextConfig.models)) {
+      nextConfig.models = [];
+      changed = true;
+    }
+
+    if (nextConfig.baseUrl === nextBaseUrl) {
+      providers[providerId] = nextConfig;
+      continue;
+    }
+
+    nextConfig.baseUrl = nextBaseUrl;
+    providers[providerId] = nextConfig;
+    changed = true;
+  }
+
+  return changed;
+}
+
+function routeBaseUrlThroughProxy(params: {
+  providerId: string;
+  proxyUrl: string;
+  currentBaseUrl?: string;
+}): string {
+  const upstreamBaseUrl = params.currentBaseUrl ?? DEFAULT_PROVIDER_BASE_URLS[params.providerId];
+  if (!upstreamBaseUrl) {
+    return params.proxyUrl;
+  }
+
+  try {
+    const proxy = new URL(params.proxyUrl);
+    const upstream = new URL(upstreamBaseUrl);
+    proxy.pathname = upstream.pathname;
+    proxy.search = upstream.search;
+    proxy.hash = "";
+    return proxy.toString().replace(/\/$/, "");
+  } catch {
+    return params.proxyUrl;
+  }
+}

plugins/openclaw/src/index.ts

@@ -3,3 +3,9 @@ export { HeadroomContextEngine } from "./engine.js";
 export { ProxyManager, normalizeAndValidateProxyUrl, isLocalProxyUrl, defaultLogger, probeHeadroomProxy } from "./proxy-manager.js";
 export { agentToOpenAI, normalizeAgentMessages, openAIToAgent } from "./convert.js";
 export { createHeadroomRetrieveTool } from "./tools/headroom-retrieve.js";
+export {
+  DEFAULT_GATEWAY_PROVIDER_IDS,
+  applyGatewayProviderBaseUrls,
+  applyGatewayProviderBaseUrlsInPlace,
+  resolveGatewayProviderIds,
+} from "./gateway-config.js";

plugins/openclaw/src/plugin/index.ts

@@ -16,6 +16,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 import { HeadroomContextEngine } from "../engine.js";
+import {
+  applyGatewayProviderBaseUrlsInPlace,
+  resolveGatewayProviderIds,
+} from "../gateway-config.js";
 import { normalizeAndValidateProxyUrl } from "../proxy-manager.js";
 import { createHeadroomRetrieveTool } from "../tools/headroom-retrieve.js";
 
@@ -34,6 +38,43 @@ export default function headroomPlugin(api: any) {
     error: (m: string) => logger.error(m),
     debug: (m: string) => logger.debug?.(m),
   });
+  const gatewayProviderIds = resolveGatewayProviderIds(config);
+
+  const applyGatewayRouting = async (activeProxyUrl: string) => {
+    if (gatewayProviderIds.length === 0) {
+      return;
+    }
+
+    try {
+      const changed = applyGatewayProviderBaseUrlsInPlace(api.config, activeProxyUrl, gatewayProviderIds);
+
+      if (changed) {
+        logger.info(
+          `[headroom] Routed ${gatewayProviderIds.join(", ")} through Headroom proxy in memory at ${activeProxyUrl}`,
+        );
+      } else {
+        logger.info(
+          `[headroom] Upstream gateway already routed in memory for ${gatewayProviderIds.join(", ")} at ${activeProxyUrl}`,
+        );
+      }
+    } catch (error) {
+      logger.warn(`[headroom] Failed to configure upstream gateway routing: ${error}`);
+    }
+  };
+
+  const ensureGatewayRouting = async () => {
+    const activeProxyUrl = engine.getProxyUrl();
+    if (!activeProxyUrl) {
+      logger.debug?.("[headroom] Deferring upstream gateway routing until proxy is available");
+      engine.ensureProxyStarted();
+      return;
+    }
+    await applyGatewayRouting(activeProxyUrl);
+  };
+
+  engine.onProxyReady(async (activeProxyUrl) => {
+    await applyGatewayRouting(activeProxyUrl);
+  });
 
   // Register as context engine
   api.registerContextEngine("headroom", () => engine);
@@ -45,5 +86,11 @@ export default function headroomPlugin(api: any) {
     return createHeadroomRetrieveTool({ proxyUrl: activeProxyUrl });
   });
 
+  api.on("gateway_start", async () => {
+    await ensureGatewayRouting();
+  });
+
+  void ensureGatewayRouting();
+
   logger.info("[headroom] Plugin registered");
 }

plugins/openclaw/src/proxy-manager.ts

@@ -18,6 +18,8 @@ export interface ProxyManagerConfig {
   pythonPath?: string;
   autoStart?: boolean;
   startupTimeoutMs?: number;
+  retryMaxAttempts?: number;
+  connectTimeoutSeconds?: number;
 }
 
 export interface ProxyManagerLogger {
@@ -47,8 +49,13 @@ interface LaunchSpec {
   args: string[];
   checkCommand: string;
   checkArgs: string[];
+  useShell?: boolean;
+  checkUseShell?: boolean;
 }
 
+const HEADROOM_MODULE_DISCOVERY_SNIPPET =
+  "import importlib.util, sys; sys.exit(0 if importlib.util.find_spec('headroom') else 1)";
+
 export class ProxyManager {
   private config: ProxyManagerConfig;
   private logger: ProxyManagerLogger;
@@ -177,7 +184,7 @@ export class ProxyManager {
     const errors: string[] = [];
 
     for (const spec of specs) {
-      if (!this.canExecute(spec.checkCommand, spec.checkArgs)) {
+      if (!this.canExecute(spec.checkCommand, spec.checkArgs, spec.checkUseShell ?? spec.useShell)) {
         this.logger.debug(`Launcher unavailable: ${spec.label}`);
         continue;
       }
@@ -185,6 +192,7 @@ export class ProxyManager {
       try {
         const child = spawn(spec.command, spec.args, {
           detached: true,
+          shell: spec.useShell === true,
           stdio: "ignore",
         });
         child.unref();
@@ -204,6 +212,16 @@ export class ProxyManager {
 
   private buildLaunchSpecs(host: string, port: string): LaunchSpec[] {
     const commonArgs = ["proxy", "--host", host, "--port", port];
+    const retryMaxAttempts = this.config.retryMaxAttempts;
+    if (Number.isInteger(retryMaxAttempts)) {
+      commonArgs.push("--retry-max-attempts", String(retryMaxAttempts));
+    }
+
+    const connectTimeoutSeconds = this.config.connectTimeoutSeconds;
+    if (Number.isInteger(connectTimeoutSeconds)) {
+      commonArgs.push("--connect-timeout-seconds", String(connectTimeoutSeconds));
+    }
+
     const specs: LaunchSpec[] = [];
 
     // 1) PATH
@@ -211,8 +229,12 @@ export class ProxyManager {
       label: "PATH: headroom",
       command: "headroom",
       args: commonArgs,
-      checkCommand: "headroom",
-      checkArgs: ["--version"],
+      checkCommand: process.platform === "win32" ? "where.exe" : "sh",
+      checkArgs: process.platform === "win32"
+        ? ["headroom"]
+        : ["-lc", "command -v headroom >/dev/null 2>&1"],
+      useShell: process.platform === "win32",
+      checkUseShell: false,
     });
 
     // 2) Local npm install (inside plugin install path)
@@ -224,14 +246,15 @@ export class ProxyManager {
       : [join(localBinDir, "headroom")];
     for (const localBin of localBins) {
       if (!existsSync(localBin)) continue;
-      specs.push({
-        label: `Local npm: ${localBin}`,
-        command: localBin,
-        args: commonArgs,
-        checkCommand: localBin,
-        checkArgs: ["--version"],
-      });
-    }
+        specs.push({
+          label: `Local npm: ${localBin}`,
+          command: localBin,
+          args: commonArgs,
+          checkCommand: localBin,
+          checkArgs: ["--version"],
+          useShell: process.platform === "win32",
+        });
+      }
 
     // 3) Global npm install
     const npmPrefix = this.getNpmGlobalPrefix();
@@ -248,6 +271,7 @@ export class ProxyManager {
           args: commonArgs,
           checkCommand: globalBin,
           checkArgs: ["--version"],
+          useShell: process.platform === "win32",
         });
       }
     }
@@ -260,7 +284,7 @@ export class ProxyManager {
         command: pyCmd,
         args: ["-m", "headroom.cli", ...commonArgs],
         checkCommand: pyCmd,
-        checkArgs: ["-c", "import headroom"],
+        checkArgs: ["-c", HEADROOM_MODULE_DISCOVERY_SNIPPET],
       });
     }
 
@@ -281,9 +305,10 @@ export class ProxyManager {
     return commands;
   }
 
-  private canExecute(command: string, args: string[]): boolean {
+  private canExecute(command: string, args: string[], useShell = false): boolean {
     try {
       const result = spawnSync(command, args, {
+        shell: useShell,
         stdio: "ignore",
         timeout: 5000,
       });

plugins/openclaw/test/engine.test.ts

@@ -1,262 +1,101 @@
-/**
- * Integration tests for HeadroomContextEngine.
- *
- * Tests the full flow: proxy management, AgentMessage conversion,
- * compression via proxy, and round-trip back to AgentMessage.
- *
- * Requires: Python 3 + headroom-ai[proxy] installed
- * Run: HEADROOM_INTEGRATION=1 npx vitest run test/engine.test.ts
- */
-import { describe, it, expect, beforeAll, afterAll, vi, afterEach } from "vitest";
-import { HeadroomContextEngine } from "../src/engine.js";
-import { agentToOpenAI, openAIToAgent } from "../src/convert.js";
-import { ProxyManager } from "../src/proxy-manager.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const mocked = vi.hoisted(() => ({
+  start: vi.fn(async () => "http://127.0.0.1:8787"),
+  stop: vi.fn(async () => undefined),
+  logger: {
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  },
+}));
+
+vi.mock("headroom-ai", () => ({
+  compress: vi.fn(),
+}));
+
+vi.mock("../src/proxy-manager.js", () => ({
+  ProxyManager: class {
+    start = mocked.start;
+    stop = mocked.stop;
+  },
+  defaultLogger: mocked.logger,
+}));
 
-const RUN = process.env.HEADROOM_INTEGRATION === "1";
-const PROXY_URL = process.env.HEADROOM_PROXY_URL ?? "http://127.0.0.1:8787";
+import { HeadroomContextEngine } from "../src/engine.js";
 
 afterEach(() => {
-  vi.restoreAllMocks();
+  mocked.start.mockReset();
+  mocked.start.mockResolvedValue("http://127.0.0.1:8787");
+  mocked.stop.mockClear();
+  mocked.logger.debug.mockClear();
+  mocked.logger.error.mockClear();
+  mocked.logger.info.mockClear();
+  mocked.logger.warn.mockClear();
 });
 
-// Proxy probing and ProxyManager.start tests live in proxy-manager.test.ts
-
-describe("AgentMessage conversion", () => {
-  it("converts user message", () => {
-    const agent = [{ role: "user", content: "hello", timestamp: Date.now() }];
-    const openai = agentToOpenAI(agent);
-    expect(openai).toHaveLength(1);
-    expect(openai[0]).toMatchObject({ role: "user", content: "hello" });
+describe("HeadroomContextEngine proxy startup helpers", () => {
+  it("bootstraps by scheduling proxy startup when enabled", async () => {
+    const engine = new HeadroomContextEngine();
+
+    await expect(
+      engine.bootstrap({
+        sessionId: "session-1",
+        sessionFile: "session.jsonl",
+      }),
+    ).resolves.toEqual({
+      bootstrapped: true,
+      reason: "proxy startup scheduled",
+    });
+    expect(mocked.start).toHaveBeenCalledTimes(1);
   });
 
-  it("converts assistant with tool_use blocks", () => {
-    const agent = [
-      {
-        role: "assistant",
-        content: [
-          { type: "text", text: "Let me search" },
-          { type: "tool_use", id: "tu_1", name: "search", input: { q: "test" } },
-        ],
-        timestamp: Date.now(),
-      },
-    ];
-    const openai = agentToOpenAI(agent);
-    expect(openai[0].role).toBe("assistant");
-    expect(openai[0].content).toBe("Let me search");
-    expect(openai[0].tool_calls).toHaveLength(1);
-    expect(openai[0].tool_calls![0].function.name).toBe("search");
-  });
+  it("removes unsubscribed proxy listeners before notifying readiness", async () => {
+    const engine = new HeadroomContextEngine();
+    const first = vi.fn();
+    const second = vi.fn();
 
-  it("converts assistant with toolCall blocks", () => {
-    const agent = [
-      {
-        role: "assistant",
-        content: [
-          { type: "text", text: "Let me search" },
-          { type: "toolCall", id: "call_1|fc_1", name: "search", arguments: { q: "test" } },
-        ],
-        timestamp: Date.now(),
-      },
-    ];
-    const openai = agentToOpenAI(agent);
-    expect(openai[0].role).toBe("assistant");
-    expect(openai[0].content).toBe("Let me search");
-    expect(openai[0].tool_calls).toHaveLength(1);
-    expect(openai[0].tool_calls![0].id).toBe("call_1|fc_1");
-    expect(openai[0].tool_calls![0].function.name).toBe("search");
-  });
+    const unsubscribeFirst = engine.onProxyReady(first);
+    engine.onProxyReady(second);
+    unsubscribeFirst();
 
-  it("converts toolResult message", () => {
-    const agent = [
-      {
-        role: "toolResult",
-        content: '{"results": [1, 2, 3]}',
-        tool_use_id: "tu_1",
-        timestamp: Date.now(),
-      },
-    ];
-    const openai = agentToOpenAI(agent);
-    expect(openai[0].role).toBe("tool");
-    expect(openai[0].content).toBe('{"results": [1, 2, 3]}');
-    expect(openai[0].tool_call_id).toBe("tu_1");
-  });
+    engine.ensureProxyStarted();
+    await engine.ensureProxyUrl();
 
-  it("round-trips user message", () => {
-    const original = [{ role: "user", content: "hello", timestamp: Date.now() }];
-    const openai = agentToOpenAI(original);
-    const back = openAIToAgent(openai);
-    expect(back[0].role).toBe("user");
-    expect(back[0].content).toBe("hello");
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledWith("http://127.0.0.1:8787");
   });
 
-  it("round-trips assistant text-only (content always array)", () => {
-    const original = [
-      {
-        role: "assistant",
-        content: [{ type: "text", text: "Hello there!" }],
-        timestamp: Date.now(),
-      },
-    ];
-    const openai = agentToOpenAI(original);
-    const back = openAIToAgent(openai);
-    expect(back[0].role).toBe("assistant");
-    // OpenClaw requires content to ALWAYS be an array for assistant messages
-    const content = back[0].content;
-    expect(Array.isArray(content)).toBe(true);
-    expect(content[0]).toEqual({ type: "text", text: "Hello there!" });
-  });
+  it("returns the existing proxy URL without starting again", async () => {
+    const engine = new HeadroomContextEngine();
 
-  it("round-trips assistant with tool calls", () => {
-    const original = [
-      {
-        role: "assistant",
-        content: [
-          { type: "text", text: "Searching..." },
-          { type: "toolCall", id: "call_1|fc_1", name: "search", arguments: { q: "test" } },
-        ],
-        timestamp: Date.now(),
-      },
-    ];
-    const openai = agentToOpenAI(original);
-    const back = openAIToAgent(openai);
-    expect(back[0].role).toBe("assistant");
-    const content = back[0].content;
-    expect(Array.isArray(content)).toBe(true);
-    expect(content).toContainEqual(expect.objectContaining({ type: "text", text: "Searching..." }));
-    expect(content).toContainEqual(
-      expect.objectContaining({ type: "toolCall", id: "call_1|fc_1", name: "search" }),
-    );
-  });
+    (engine as { proxyUrl: string | null }).proxyUrl = "http://127.0.0.1:8787";
 
-  it("round-trips toolResult", () => {
-    const original = [
-      {
-        role: "toolResult",
-        content: '{"data": true}',
-        tool_use_id: "tu_1",
-        timestamp: Date.now(),
-      },
-    ];
-    const openai = agentToOpenAI(original);
-    const back = openAIToAgent(openai);
-    expect(back[0].role).toBe("toolResult");
-    expect(back[0].content).toEqual([{ type: "text", text: '{"data": true}' }]);
-    expect(back[0].tool_use_id).toBe("tu_1");
+    await expect(engine.ensureProxyUrl()).resolves.toBe("http://127.0.0.1:8787");
+    expect(mocked.start).not.toHaveBeenCalled();
   });
-});
 
-if (RUN) {
-  describe("ProxyManager", () => {
-    it("connects to configured proxy URL", { timeout: 30000 }, async () => {
-      const manager = new ProxyManager({ proxyUrl: PROXY_URL });
-      try {
-        const url = await manager.start();
-        expect(url).toMatch(/^http:\/\/(127\.0\.0\.1|localhost):\d+$/);
+  it("throws when proxy startup is disabled", async () => {
+    const engine = new HeadroomContextEngine({ enabled: false });
 
-        // Verify health
-        const resp = await fetch(`${url}/health`);
-        expect(resp.ok).toBe(true);
-      } finally {
-        await manager.stop();
-      }
-    });
+    await expect(engine.ensureProxyUrl()).rejects.toThrow("Headroom proxy startup is disabled");
+    expect(mocked.start).not.toHaveBeenCalled();
   });
 
-  describe("HeadroomContextEngine", () => {
-    let engine: HeadroomContextEngine;
-
-    beforeAll(async () => {
-      engine = new HeadroomContextEngine({ proxyUrl: PROXY_URL });
-      await engine.bootstrap({
-        sessionId: "test-session",
-        sessionFile: "/tmp/test-session.jsonl",
-      });
-    }, 30000);
-
-    afterAll(async () => {
-      await engine.dispose();
-    });
-
-    it("assemble() compresses tool outputs", { timeout: 15000 }, async () => {
-    // Simulate an OpenClaw agent conversation with large tool result
-    const serverData = Array.from({ length: 100 }, (_, i) => ({
-      id: i + 1,
-      name: `server-${i + 1}`,
-      status: i % 15 === 0 ? "critical" : i % 5 === 0 ? "warning" : "healthy",
-      cpu: Math.round(Math.random() * 100),
-      memory: Math.round(Math.random() * 100),
-      region: ["us-east-1", "eu-west-1", "ap-southeast-1"][i % 3],
-      description: `Production server ${i + 1} running service-${["auth", "payment", "user", "api"][i % 4]}`,
-      lastAlert: i % 15 === 0 ? `Disk usage at ${90 + (i % 10)}%` : null,
-    }));
-
-    const messages = [
-      { role: "user", content: "Check the fleet status", timestamp: Date.now() },
-      {
-        role: "assistant",
-        content: [
-          { type: "tool_use", id: "tu_fleet", name: "getFleetStatus", input: {} },
-        ],
-        timestamp: Date.now(),
-      },
-      {
-        role: "toolResult",
-        content: JSON.stringify(serverData),
-        tool_use_id: "tu_fleet",
-        timestamp: Date.now(),
-      },
-      { role: "user", content: "Which servers are critical?", timestamp: Date.now() },
-    ];
+  it("schedules startup and returns original messages when assembling before proxy readiness", async () => {
+    const engine = new HeadroomContextEngine();
+    const messages = [{ role: "user", content: "hello" }];
 
-    const result = await engine.assemble({
-      sessionId: "test-session",
+    await expect(
+      engine.assemble({
+        sessionId: "session-1",
+        messages,
+      }),
+    ).resolves.toEqual({
       messages,
-      model: "claude-sonnet-4-5",
-    });
-
-    console.log(
-      `  assemble(): estimatedTokens=${result.estimatedTokens}, ` +
-        `systemPrompt=${result.systemPromptAddition ? "yes" : "no"}`,
-    );
-
-    // Messages should be returned (compressed or not)
-    expect(result.messages.length).toBeGreaterThan(0);
-    // First and last messages should still be user messages
-    expect(result.messages[0].role).toBe("user");
-    expect(result.messages[result.messages.length - 1].role).toBe("user");
-    });
-
-    it("assemble() preserves small conversations", { timeout: 15000 }, async () => {
-    const messages = [
-      { role: "user", content: "Hello", timestamp: Date.now() },
-      { role: "assistant", content: "Hi there!", timestamp: Date.now() },
-    ];
-
-    const result = await engine.assemble({
-      sessionId: "test-session",
-      messages,
-    });
-
-    expect(result.messages).toHaveLength(2);
-    expect(result.messages[0].content).toBe("Hello");
-    expect(result.messages[1].content).toBe("Hi there!");
-    });
-
-    it("compact() returns success (compression handled in assemble)", async () => {
-    const result = await engine.compact({
-      sessionId: "test-session",
-      sessionFile: "/tmp/test.jsonl",
-    });
-
-    expect(result.ok).toBe(true);
-    expect(result.compacted).toBe(true);
-    });
-
-    it("getStats() returns compression statistics", () => {
-    const stats = engine.getStats();
-    expect(stats).toHaveProperty("totalCompressions");
-    expect(stats).toHaveProperty("totalTokensSaved");
-    expect(stats.totalCompressions).toBeGreaterThanOrEqual(0);
+      estimatedTokens: 0,
     });
+    expect(mocked.start).toHaveBeenCalledTimes(1);
   });
-}
+});

plugins/openclaw/test/gateway-config.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyGatewayProviderBaseUrls,
+  applyGatewayProviderBaseUrlsInPlace,
+  resolveGatewayProviderIds,
+} from "../src/gateway-config.js";
+
+describe("resolveGatewayProviderIds", () => {
+  it("routes openai-codex by default", () => {
+    expect(resolveGatewayProviderIds(undefined)).toEqual(["openai-codex"]);
+  });
+
+  it("allows an explicit provider list to override the default", () => {
+    expect(
+      resolveGatewayProviderIds({
+        gatewayProviderIds: ["anthropic", "github-copilot", "minimax-portal"],
+      }),
+    ).toEqual(["anthropic", "github-copilot", "minimax-portal"]);
+  });
+
+  it("normalizes explicit provider ids and friendly aliases", () => {
+    expect(
+      resolveGatewayProviderIds({
+        gatewayProviderIds: [" claude ", "", "copilot", "codex", "gemini", "anthropic"],
+      }),
+    ).toEqual(["anthropic", "github-copilot", "openai-codex", "google"]);
+  });
+
+  it("allows routing to be disabled", () => {
+    expect(resolveGatewayProviderIds({ routeCodexViaProxy: false })).toEqual([]);
+  });
+});
+
+describe("applyGatewayProviderBaseUrls", () => {
+  it("creates an openai-codex provider config when missing", () => {
+    const result = applyGatewayProviderBaseUrls({}, "http://127.0.0.1:8787", ["openai-codex"]);
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers["openai-codex"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/backend-api",
+      models: [],
+    });
+  });
+
+  it("creates provider configs for multiple configured provider ids", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {},
+      "http://127.0.0.1:8787",
+      ["anthropic", "openrouter", "google", "minimax-portal"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers).toEqual({
+      anthropic: {
+        baseUrl: "http://127.0.0.1:8787",
+        models: [],
+      },
+      openrouter: {
+        baseUrl: "http://127.0.0.1:8787",
+        models: [],
+      },
+      google: {
+        baseUrl: "http://127.0.0.1:8787",
+        models: [],
+      },
+      "minimax-portal": {
+        baseUrl: "http://127.0.0.1:8787",
+        models: [],
+      },
+    });
+  });
+
+  it("preserves existing provider config fields", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            "openai-codex": {
+              api: "openai-codex-responses",
+              baseUrl: "https://chatgpt.com/backend-api",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["openai-codex"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers["openai-codex"]).toEqual({
+      api: "openai-codex-responses",
+      baseUrl: "http://127.0.0.1:8787/backend-api",
+      models: [],
+    });
+  });
+
+  it("is a no-op when the provider already points at headroom", () => {
+    const cfg = {
+      models: {
+        providers: {
+          "openai-codex": {
+            baseUrl: "http://127.0.0.1:8787/backend-api",
+            models: [],
+          },
+        },
+      },
+    };
+
+    const result = applyGatewayProviderBaseUrls(cfg, "http://127.0.0.1:8787", ["openai-codex"]);
+
+    expect(result.changed).toBe(false);
+    expect(result.config).toEqual(cfg);
+  });
+
+  it("preserves upstream path segments when routing through the proxy", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            anthropic: {
+              baseUrl: "https://api.anthropic.com/v1",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["anthropic"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers.anthropic).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1",
+      models: [],
+    });
+  });
+
+  it("preserves protocol-specific GitHub Copilot OpenAI-family paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            "github-copilot": {
+              baseUrl: "https://api.githubcopilot.com/v1",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["github-copilot"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers["github-copilot"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1",
+      models: [],
+    });
+  });
+
+  it("preserves protocol-specific GitHub Copilot Claude-family paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            "github-copilot": {
+              baseUrl: "https://api.githubcopilot.com/anthropic",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["github-copilot"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers["github-copilot"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/anthropic",
+      models: [],
+    });
+  });
+
+  it("preserves OpenAI-compatible /api/v1 paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            openrouter: {
+              baseUrl: "https://openrouter.ai/api/v1",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["openrouter"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers.openrouter).toEqual({
+      baseUrl: "http://127.0.0.1:8787/api/v1",
+      models: [],
+    });
+  });
+
+  it("preserves Gemini /v1beta paths", () => {
+    const result = applyGatewayProviderBaseUrls(
+      {
+        models: {
+          providers: {
+            google: {
+              baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+            },
+          },
+        },
+      },
+      "http://127.0.0.1:8787",
+      ["google"],
+    );
+
+    expect(result.changed).toBe(true);
+    expect((result.config as any).models.providers.google).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1beta",
+      models: [],
+    });
+  });
+
+  it("does not invent a GitHub Copilot proxy baseUrl without an upstream baseUrl", () => {
+    const result = applyGatewayProviderBaseUrls({}, "http://127.0.0.1:8787", ["github-copilot"]);
+
+    expect(result.changed).toBe(false);
+    expect((result.config as any).models?.providers?.["github-copilot"]).toBeUndefined();
+  });
+});
+
+describe("applyGatewayProviderBaseUrlsInPlace", () => {
+  it("updates the live config object in place", () => {
+    const cfg: any = { models: { providers: {} } };
+
+    const changed = applyGatewayProviderBaseUrlsInPlace(
+      cfg,
+      "http://127.0.0.1:8787",
+      ["openai-codex"],
+    );
+
+    expect(changed).toBe(true);
+    expect(cfg.models.providers["openai-codex"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/backend-api",
+      models: [],
+    });
+  });
+
+  it("does not clobber existing provider logic when changing only the base URL", () => {
+    const cfg: any = {
+      models: {
+        providers: {
+          "openai-codex": {
+            api: "openai-codex-responses",
+            baseUrl: "https://chatgpt.com/backend-api",
+            envKey: "OPENAI_API_KEY",
+            models: ["gpt-5.3-codex"],
+          },
+        },
+      },
+    };
+
+    const changed = applyGatewayProviderBaseUrlsInPlace(
+      cfg,
+      "http://127.0.0.1:8787",
+      ["openai-codex"],
+    );
+
+    expect(changed).toBe(true);
+    expect(cfg.models.providers["openai-codex"]).toEqual({
+      api: "openai-codex-responses",
+      envKey: "OPENAI_API_KEY",
+      baseUrl: "http://127.0.0.1:8787/backend-api",
+      models: ["gpt-5.3-codex"],
+    });
+  });
+});

plugins/openclaw/test/plugin-runtime-routing.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const mocked = vi.hoisted(() => ({
+  ensureProxyUrl: vi.fn(async () => "http://127.0.0.1:8787"),
+  ensureProxyStarted: vi.fn(),
+  getProxyUrl: vi.fn(() => null as string | null),
+  createHeadroomRetrieveTool: vi.fn(({ proxyUrl }: { proxyUrl: string }) => ({ proxyUrl })),
+}));
+
+const proxyReadyListeners: Array<(proxyUrl: string) => void | Promise<void>> = [];
+
+vi.mock("../src/engine.js", () => ({
+  HeadroomContextEngine: class {
+    ensureProxyUrl = mocked.ensureProxyUrl;
+    ensureProxyStarted = mocked.ensureProxyStarted;
+    getProxyUrl = mocked.getProxyUrl;
+    onProxyReady(listener: (proxyUrl: string) => void | Promise<void>) {
+      proxyReadyListeners.push(listener);
+      return () => {};
+    }
+  },
+}));
+
+vi.mock("../src/tools/headroom-retrieve.js", () => ({
+  createHeadroomRetrieveTool: mocked.createHeadroomRetrieveTool,
+}));
+
+import headroomPlugin from "../src/plugin/index.js";
+
+afterEach(() => {
+  mocked.ensureProxyUrl.mockClear();
+  mocked.ensureProxyStarted.mockClear();
+  mocked.getProxyUrl.mockClear();
+  mocked.createHeadroomRetrieveTool.mockClear();
+  proxyReadyListeners.length = 0;
+});
+
+describe("headroomPlugin runtime routing", () => {
+  it("routes configured providers in memory once the proxy becomes available", async () => {
+    const gatewayHandlers = new Map<string, () => Promise<void>>();
+    const writeConfigFile = vi.fn();
+    const loadConfig = vi.fn(() => ({
+      models: {
+        providers: {
+          anthropic: {
+            api: "anthropic-messages",
+          },
+        },
+      },
+    }));
+
+    const api: any = {
+      config: {
+        plugins: {
+          entries: {
+            headroom: {
+              config: {
+                gatewayProviderIds: ["codex", "claude", "copilot", "gemini", "openrouter"],
+              },
+            },
+          },
+        },
+        models: {
+          providers: {
+            anthropic: {
+              api: "anthropic-messages",
+              baseUrl: "https://api.anthropic.com",
+            },
+            "github-copilot": {
+              baseUrl: "https://api.githubcopilot.com/v1",
+            },
+            google: {
+              baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+            },
+            openrouter: {
+              baseUrl: "https://openrouter.ai/api/v1",
+            },
+          },
+        },
+      },
+      logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+      },
+      registerContextEngine: vi.fn(),
+      registerTool: vi.fn(),
+      on: vi.fn((event: string, handler: () => Promise<void>) => {
+        gatewayHandlers.set(event, handler);
+      }),
+      runtime: {
+        config: {
+          loadConfig,
+          writeConfigFile,
+        },
+      },
+    };
+
+    headroomPlugin(api);
+    await Promise.resolve();
+
+    expect(mocked.ensureProxyUrl).not.toHaveBeenCalled();
+    expect(mocked.ensureProxyStarted).toHaveBeenCalledTimes(1);
+    expect(writeConfigFile).not.toHaveBeenCalled();
+    expect(loadConfig).not.toHaveBeenCalled();
+    expect(api.config.models.providers["openai-codex"]).toBeUndefined();
+
+    await proxyReadyListeners[0]?.("http://127.0.0.1:8787");
+
+    expect(api.config.models.providers["openai-codex"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/backend-api",
+      models: [],
+    });
+    expect(api.config.models.providers.anthropic).toEqual({
+      api: "anthropic-messages",
+      baseUrl: "http://127.0.0.1:8787",
+      models: [],
+    });
+    expect(api.config.models.providers["github-copilot"]).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1",
+      models: [],
+    });
+    expect(api.config.models.providers.google).toEqual({
+      baseUrl: "http://127.0.0.1:8787/v1beta",
+      models: [],
+    });
+    expect(api.config.models.providers.openrouter).toEqual({
+      baseUrl: "http://127.0.0.1:8787/api/v1",
+      models: [],
+    });
+
+    const gatewayStart = gatewayHandlers.get("gateway_start");
+    expect(gatewayStart).toBeTypeOf("function");
+    await gatewayStart?.();
+    expect(mocked.ensureProxyStarted).toHaveBeenCalledTimes(2);
+    expect(writeConfigFile).not.toHaveBeenCalled();
+    expect(loadConfig).not.toHaveBeenCalled();
+    expect(mocked.ensureProxyUrl).not.toHaveBeenCalled();
+  });
+});

plugins/openclaw/test/proxy-manager.test.ts

@@ -204,6 +204,53 @@ describe("ProxyManager launch internals", () => {
     expect(commands).toContain("py");
   });
 
+  it("uses lightweight PATH checks instead of booting the headroom CLI", () => {
+    const manager = new ProxyManager({});
+    const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
+    const pathSpec = specs[0];
+
+    expect(pathSpec.command).toBe("headroom");
+    expect(pathSpec.args).toEqual(["proxy", "--host", "127.0.0.1", "--port", "8787"]);
+    if (process.platform === "win32") {
+      expect(pathSpec.checkCommand).toBe("where.exe");
+      expect(pathSpec.checkArgs).toEqual(["headroom"]);
+      expect(pathSpec.checkUseShell).toBe(false);
+    } else {
+      expect(pathSpec.checkCommand).toBe("sh");
+      expect(pathSpec.checkArgs).toEqual(["-lc", "command -v headroom >/dev/null 2>&1"]);
+    }
+  });
+
+  it("passes through fast-fail launch flags when configured", () => {
+    const manager = new ProxyManager({ retryMaxAttempts: 1, connectTimeoutSeconds: 3 });
+    const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
+    const pathSpec = specs[0];
+
+    expect(pathSpec.args).toEqual([
+      "proxy",
+      "--host",
+      "127.0.0.1",
+      "--port",
+      "8787",
+      "--retry-max-attempts",
+      "1",
+      "--connect-timeout-seconds",
+      "3",
+    ]);
+  });
+
+  it("uses lightweight module discovery for python fallback checks", () => {
+    const manager = new ProxyManager({ pythonPath: "C:\\Python311\\python.exe" });
+    const specs = (manager as any).buildLaunchSpecs("127.0.0.1", "8787") as Array<Record<string, unknown>>;
+    const pythonSpec = specs.find((spec) => spec.command === "C:\\Python311\\python.exe");
+
+    expect(pythonSpec).toBeDefined();
+    expect(pythonSpec?.checkArgs).toEqual([
+      "-c",
+      "import importlib.util, sys; sys.exit(0 if importlib.util.find_spec('headroom') else 1)",
+    ]);
+  });
+
   it("uses first available launcher from provided specs", async () => {
     const manager = new ProxyManager({});
     (manager as any).buildLaunchSpecs = () => [
@@ -229,6 +276,27 @@ describe("ProxyManager launch internals", () => {
     expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining("second-node"));
   });
 
+  it("supports shell-backed launch specs for PATH shims and script wrappers", async () => {
+    const manager = new ProxyManager({});
+    const shellBuiltin = process.platform === "win32" ? "dir" : ":";
+    (manager as any).buildLaunchSpecs = () => [
+      {
+        label: "shell-backed",
+        command: shellBuiltin,
+        args: [],
+        checkCommand: shellBuiltin,
+        checkArgs: [],
+        useShell: true,
+      },
+    ];
+    const infoSpy = vi.spyOn((manager as any).logger, "info");
+
+    await (manager as any).startHeadroomProxy("http://127.0.0.1:8787", 8787);
+
+    expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining("Auto-start launcher selected"));
+    expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining("shell-backed"));
+  });
+
   it("throws when no launcher is executable", async () => {
     const manager = new ProxyManager({});
     (manager as any).buildLaunchSpecs = () => [

tests/test_cli/test_wrap_openclaw.py

@@ -67,6 +67,18 @@ def test_wrap_openclaw_default_installs_from_npm_and_restarts(runner: CliRunner)
     assert ["openclaw", "gateway", "restart"] in cmds
     assert ["openclaw", "plugins", "inspect", "headroom"] in cmds
 
+    config_set_index = next(
+        i
+        for i, cmd in enumerate(cmds)
+        if cmd[:4] == ["openclaw", "config", "set", "plugins.entries.headroom"]
+    )
+    install_index = next(
+        i
+        for i, cmd in enumerate(cmds)
+        if cmd[:4] == ["openclaw", "plugins", "install", "--dangerously-force-unsafe-install"]
+    )
+    assert config_set_index < install_index
+
     # Verify plugin install in npm mode does not set cwd
     install_call = next(
         c
@@ -90,6 +102,8 @@ def test_wrap_openclaw_default_installs_from_npm_and_restarts(runner: CliRunner)
     assert payload["config"]["proxyPort"] == 8787
     assert payload["config"]["autoStart"] is True
     assert payload["config"]["startupTimeoutMs"] == 20000
+    assert payload["config"]["gatewayProviderIds"] == ["openai-codex"]
+    assert payload["config"]["pythonPath"] == wrap_cli.sys.executable
 
 
 def test_wrap_openclaw_skip_build_and_no_restart(runner: CliRunner, plugin_dir: Path) -> None:
@@ -272,6 +286,143 @@ def test_wrap_openclaw_verbose_prints_install_restart_and_inspect_output(
     assert "inspect-ok" in result.output
 
 
+def test_wrap_openclaw_starts_gateway_when_restart_fails(runner: CliRunner) -> None:
+    calls: list[dict] = []
+
+    def which(name: str) -> str | None:
+        return {"openclaw": "openclaw", "npm": "npm"}.get(name)
+
+    def run(cmd, **kwargs):  # noqa: ANN001
+        calls.append({"cmd": list(cmd), **kwargs})
+        if cmd[:3] == ["openclaw", "gateway", "restart"]:
+            return MagicMock(returncode=1, stdout="", stderr="gateway not running")
+        if cmd[:3] == ["openclaw", "gateway", "start"]:
+            return MagicMock(returncode=0, stdout="started-ok", stderr="")
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+        with patch("headroom.cli.wrap.subprocess.run", side_effect=run):
+            result = runner.invoke(main, ["wrap", "openclaw", "--verbose"])
+
+    assert result.exit_code == 0, result.output
+    cmds = [c["cmd"] for c in calls]
+    assert ["openclaw", "gateway", "restart"] in cmds
+    assert ["openclaw", "gateway", "start"] in cmds
+    assert "Gateway started." in result.output
+    assert "started-ok" in result.output
+
+
+def test_wrap_openclaw_accepts_repeatable_gateway_provider_ids(runner: CliRunner) -> None:
+    calls: list[dict] = []
+
+    def which(name: str) -> str | None:
+        return {"openclaw": "openclaw", "npm": "npm"}.get(name)
+
+    with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+        with patch("headroom.cli.wrap.subprocess.run", side_effect=_make_successful_run(calls)):
+            result = runner.invoke(
+                main,
+                [
+                    "wrap",
+                    "openclaw",
+                    "--gateway-provider-id",
+                    "openai-codex",
+                    "--gateway-provider-id",
+                    "anthropic",
+                    "--no-restart",
+                ],
+            )
+
+    assert result.exit_code == 0, result.output
+    set_entry = next(
+        c
+        for c in calls
+        if c["cmd"][:4] == ["openclaw", "config", "set", "plugins.entries.headroom"]
+    )
+    payload = json.loads(set_entry["cmd"][4])
+    assert payload["config"]["gatewayProviderIds"] == ["openai-codex", "anthropic"]
+
+
+def test_normalize_openclaw_gateway_provider_ids_dedupes_blanks_and_defaults() -> None:
+    assert wrap_cli._normalize_openclaw_gateway_provider_ids(
+        (" openai-codex ", "", "anthropic", "openai-codex", "  ")
+    ) == ["openai-codex", "anthropic"]
+    assert wrap_cli._normalize_openclaw_gateway_provider_ids(None) == ["openai-codex"]
+
+
+def test_read_openclaw_config_value_handles_missing_and_raw_strings() -> None:
+    missing = MagicMock(returncode=1, stdout="", stderr="missing")
+    raw_string = MagicMock(returncode=0, stdout="plain-text-value\n", stderr="")
+
+    with patch("headroom.cli.wrap.subprocess.run", side_effect=[missing, raw_string]):
+        assert wrap_cli._read_openclaw_config_value("openclaw", "plugins.entries.headroom") is None
+        assert (
+            wrap_cli._read_openclaw_config_value(
+                "openclaw", "plugins.entries.headroom.config.pythonPath"
+            )
+            == "plain-text-value"
+        )
+
+
+def test_build_openclaw_plugin_entry_sets_and_clears_python_path() -> None:
+    with_python = wrap_cli._build_openclaw_plugin_entry(
+        existing_entry={"config": {"customFlag": True}},
+        proxy_port=8787,
+        startup_timeout_ms=20000,
+        python_path="C:\\Python312\\python.exe",
+        no_auto_start=False,
+        gateway_provider_ids=("openai-codex",),
+        enabled=True,
+    )
+    assert with_python["config"]["pythonPath"] == "C:\\Python312\\python.exe"
+
+    without_python = wrap_cli._build_openclaw_plugin_entry(
+        existing_entry={"config": {"pythonPath": "C:\\Old\\python.exe", "customFlag": True}},
+        proxy_port=8787,
+        startup_timeout_ms=20000,
+        python_path=None,
+        no_auto_start=False,
+        gateway_provider_ids=("openai-codex",),
+        enabled=True,
+    )
+    assert "pythonPath" not in without_python["config"]
+    assert without_python["config"]["customFlag"] is True
+
+
+def test_wrap_openclaw_no_auto_start_does_not_default_python_path(
+    runner: CliRunner, plugin_dir: Path
+) -> None:
+    calls: list[dict] = []
+
+    def which(name: str) -> str | None:
+        return {"openclaw": "openclaw", "npm": "npm"}.get(name)
+
+    with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+        with patch("headroom.cli.wrap.subprocess.run", side_effect=_make_successful_run(calls)):
+            result = runner.invoke(
+                main,
+                [
+                    "wrap",
+                    "openclaw",
+                    "--plugin-path",
+                    str(plugin_dir),
+                    "--skip-build",
+                    "--no-auto-start",
+                    "--no-restart",
+                ],
+            )
+
+    assert result.exit_code == 0, result.output
+    set_entry = next(
+        c
+        for c in calls
+        if c["cmd"][:4] == ["openclaw", "config", "set", "plugins.entries.headroom"]
+    )
+    payload = json.loads(set_entry["cmd"][4])
+    assert payload["config"]["autoStart"] is False
+    assert "pythonPath" not in payload["config"]
+
+
 def test_wrap_openclaw_fails_for_npm_mode_hook_pack_bug_without_local_fallback(
     runner: CliRunner,
 ) -> None:
@@ -448,3 +599,102 @@ def test_copy_openclaw_plugin_into_extensions_handles_missing_and_existing_dist(
     assert not (target_dist / "old.js").exists()
     assert (target_hook_shim / "index.js").exists()
     assert not (target_hook_shim / "old.js").exists()
+
+
+def test_unwrap_openclaw_disables_plugin_and_restores_legacy_slot(runner: CliRunner) -> None:
+    calls: list[dict] = []
+
+    def which(name: str) -> str | None:
+        return {"openclaw": "openclaw"}.get(name)
+
+    def run(cmd, **kwargs):  # noqa: ANN001
+        calls.append({"cmd": list(cmd), **kwargs})
+        if cmd[:4] == ["openclaw", "config", "get", "plugins.entries.headroom"]:
+            return MagicMock(
+                returncode=0,
+                stdout=json.dumps(
+                    {
+                        "enabled": True,
+                        "config": {
+                            "proxyPort": 8787,
+                            "gatewayProviderIds": ["openai-codex"],
+                            "customFlag": True,
+                        },
+                    }
+                ),
+                stderr="",
+            )
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+        with patch("headroom.cli.wrap.subprocess.run", side_effect=run):
+            result = runner.invoke(main, ["unwrap", "openclaw"])
+
+    assert result.exit_code == 0, result.output
+    set_entry = next(
+        c
+        for c in calls
+        if c["cmd"][:4] == ["openclaw", "config", "set", "plugins.entries.headroom"]
+    )
+    payload = json.loads(set_entry["cmd"][4])
+    assert payload == {"enabled": False, "config": {"customFlag": True}}
+
+    set_slot = next(
+        c
+        for c in calls
+        if c["cmd"][:4] == ["openclaw", "config", "set", "plugins.slots.contextEngine"]
+    )
+    assert json.loads(set_slot["cmd"][4]) == "legacy"
+    assert ["openclaw", "gateway", "restart"] in [c["cmd"] for c in calls]
+
+
+def test_unwrap_openclaw_no_restart_skips_gateway_restart(runner: CliRunner) -> None:
+    calls: list[dict] = []
+
+    def which(name: str) -> str | None:
+        return {"openclaw": "openclaw"}.get(name)
+
+    def run(cmd, **kwargs):  # noqa: ANN001
+        calls.append({"cmd": list(cmd), **kwargs})
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+        with patch("headroom.cli.wrap.subprocess.run", side_effect=run):
+            result = runner.invoke(main, ["unwrap", "openclaw", "--no-restart"])
+
+    assert result.exit_code == 0, result.output
+    assert ["openclaw", "gateway", "restart"] not in [c["cmd"] for c in calls]
+
+
+def test_unwrap_openclaw_fails_when_openclaw_missing(runner: CliRunner) -> None:
+    with patch("headroom.cli.wrap.shutil.which", return_value=None):
+        result = runner.invoke(main, ["unwrap", "openclaw"])
+
+    assert result.exit_code != 0
+    assert "'openclaw' not found in PATH" in result.output
+
+
+def test_unwrap_openclaw_verbose_prints_gateway_and_inspect_output(runner: CliRunner) -> None:
+    def which(name: str) -> str | None:
+        return {"openclaw": "openclaw"}.get(name)
+
+    def run(cmd, **kwargs):  # noqa: ANN001
+        if cmd[:4] == ["openclaw", "config", "get", "plugins.entries.headroom"]:
+            return MagicMock(
+                returncode=0,
+                stdout=json.dumps({"enabled": True, "config": {"proxyPort": 8787}}),
+                stderr="",
+            )
+        if cmd[:3] == ["openclaw", "gateway", "restart"]:
+            return MagicMock(returncode=0, stdout="gateway-restarted", stderr="")
+        if cmd[:3] == ["openclaw", "plugins", "inspect"]:
+            return MagicMock(returncode=0, stdout="inspect-disabled", stderr="")
+        return MagicMock(returncode=0, stdout="", stderr="")
+
+    with patch("headroom.cli.wrap.shutil.which", side_effect=which):
+        with patch("headroom.cli.wrap.subprocess.run", side_effect=run):
+            result = runner.invoke(main, ["unwrap", "openclaw", "--verbose"])
+
+    assert result.exit_code == 0, result.output
+    assert "gateway-restarted" in result.output
+    assert "inspect-disabled" in result.output

tests/test_cli_proxy_env.py

@@ -142,6 +142,30 @@ class TestCLIProxyEnvVars:
         assert captured_config["config"].openai_api_url == "http://my-vllm:4000"
         assert captured_config["config"].gemini_api_url == "http://my-gemini:5000"
 
+    def test_retry_and_connect_timeout_cli_flags(self, runner):
+        """Fast-fail CLI flags should map into ProxyConfig."""
+        captured_config = {}
+
+        def mock_run_server(config):
+            captured_config["config"] = config
+
+        with patch("headroom.proxy.server.run_server", mock_run_server):
+            result = runner.invoke(
+                main,
+                [
+                    "proxy",
+                    "--retry-max-attempts",
+                    "1",
+                    "--connect-timeout-seconds",
+                    "3",
+                ],
+                catch_exceptions=False,
+            )
+
+        assert result.exit_code == 0, result.output
+        assert captured_config["config"].retry_max_attempts == 1
+        assert captured_config["config"].connect_timeout_seconds == 3
+
 
 class TestCLIProxyBackend:
     """Test that litellm-* backends are accepted by the CLI."""

tests/test_openai_codex_routing.py

@@ -0,0 +1,217 @@
+import base64
+import json
+import sys
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import anyio
+import pytest
+from fastapi import Request
+
+from headroom.proxy.handlers.openai import (
+    OpenAIHandlerMixin,
+    _resolve_codex_routing_headers,
+)
+
+
+def _jwt(payload: dict) -> str:
+    header = {"alg": "none", "typ": "JWT"}
+
+    def encode(part: dict) -> str:
+        raw = json.dumps(part, separators=(",", ":")).encode("utf-8")
+        return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+    return f"{encode(header)}.{encode(payload)}."
+
+
+def test_resolve_codex_routing_prefers_explicit_header():
+    headers, is_chatgpt = _resolve_codex_routing_headers(
+        {
+            "Authorization": "Bearer sk-test",
+            "ChatGPT-Account-ID": "acct-explicit",
+        }
+    )
+
+    assert is_chatgpt is True
+    assert headers["ChatGPT-Account-ID"] == "acct-explicit"
+
+
+def test_resolve_codex_routing_derives_account_id_from_oauth_jwt():
+    token = _jwt(
+        {
+            "https://api.openai.com/auth": {
+                "chatgpt_account_id": "acct-from-jwt",
+            }
+        }
+    )
+
+    headers, is_chatgpt = _resolve_codex_routing_headers(
+        {
+            "authorization": f"Bearer {token}",
+        }
+    )
+
+    assert is_chatgpt is True
+    assert headers["ChatGPT-Account-ID"] == "acct-from-jwt"
+
+
+def test_resolve_codex_routing_leaves_regular_openai_bearer_tokens_unchanged():
+    token = _jwt({"aud": ["https://api.openai.com/v1"]})
+
+    headers, is_chatgpt = _resolve_codex_routing_headers(
+        {
+            "authorization": f"Bearer {token}",
+        }
+    )
+
+    assert is_chatgpt is False
+    assert "ChatGPT-Account-ID" not in headers
+
+
+def test_resolve_codex_routing_returns_none_without_bearer_auth():
+    headers, is_chatgpt = _resolve_codex_routing_headers({})
+
+    assert is_chatgpt is False
+    assert headers == {}
+
+
+def test_resolve_codex_routing_ignores_non_jwt_bearer_tokens():
+    headers, is_chatgpt = _resolve_codex_routing_headers(
+        {
+            "authorization": "Bearer not-a-jwt",
+        }
+    )
+
+    assert is_chatgpt is False
+    assert headers["authorization"] == "Bearer not-a-jwt"
+
+
+def test_resolve_codex_routing_ignores_invalid_jwt_payloads():
+    invalid_payload = base64.urlsafe_b64encode(b"not-json").decode("ascii").rstrip("=")
+    token = f"test-header.{invalid_payload}.signature"
+
+    headers, is_chatgpt = _resolve_codex_routing_headers(
+        {
+            "authorization": f"Bearer {token}",
+        }
+    )
+
+    assert is_chatgpt is False
+    assert headers["authorization"] == f"Bearer {token}"
+
+
+class _DummyMetrics:
+    async def record_request(self, **kwargs):  # noqa: ANN003
+        return None
+
+    async def record_failed(self):
+        return None
+
+
+class _DummyTokenizer:
+    def count_messages(self, messages):
+        return len(messages)
+
+
+class _ResponseStub:
+    def json(self):
+        return {"usage": {"input_tokens": 2, "output_tokens": 1}}
+
+
+class _DummyOpenAIHandler(OpenAIHandlerMixin):
+    OPENAI_API_URL = "https://api.openai.com"
+
+    def __init__(self) -> None:
+        self.rate_limiter = None
+        self.metrics = _DummyMetrics()
+        self.config = SimpleNamespace(optimize=False)
+        self.usage_reporter = None
+        self.openai_provider = SimpleNamespace()
+        self.anthropic_backend = None
+        self.cost_tracker = None
+        self.captured_request: tuple[str, str, dict, dict] | None = None
+
+    async def _next_request_id(self) -> str:
+        return "req-1"
+
+    def _extract_tags(self, headers: dict[str, str]) -> list[str]:
+        return []
+
+    async def _retry_request(self, method: str, url: str, headers: dict, body: dict):
+        self.captured_request = (method, url, headers, body)
+        return _ResponseStub()
+
+
+def _build_request(body: dict, headers: dict[str, str]) -> Request:
+    payload = json.dumps(body).encode("utf-8")
+
+    async def receive():
+        return {"type": "http.request", "body": payload, "more_body": False}
+
+    scope = {
+        "type": "http",
+        "asgi": {"version": "3.0"},
+        "http_version": "1.1",
+        "method": "POST",
+        "scheme": "https",
+        "path": "/v1/responses",
+        "raw_path": b"/v1/responses",
+        "query_string": b"",
+        "headers": [
+            (key.lower().encode("utf-8"), value.encode("utf-8")) for key, value in headers.items()
+        ],
+        "client": ("127.0.0.1", 12345),
+        "server": ("testserver", 443),
+    }
+    return Request(scope, receive)
+
+
+def test_handle_openai_responses_routes_chatgpt_auth_to_backend_api(monkeypatch):
+    token = _jwt(
+        {
+            "https://api.openai.com/auth": {
+                "chatgpt_account_id": "acct-from-jwt",
+            }
+        }
+    )
+    request = _build_request(
+        {"model": "gpt-5.4", "input": "hello"},
+        {"Authorization": f"Bearer {token}"},
+    )
+    handler = _DummyOpenAIHandler()
+
+    monkeypatch.setattr("headroom.tokenizers.get_tokenizer", lambda model: _DummyTokenizer())
+
+    anyio.run(handler.handle_openai_responses, request)
+
+    assert handler.captured_request is not None
+    method, url, headers, body = handler.captured_request
+    assert method == "POST"
+    assert url == "https://chatgpt.com/backend-api/codex/responses"
+    assert headers["ChatGPT-Account-ID"] == "acct-from-jwt"
+    assert body["input"] == "hello"
+
+
+class _DummyWebSocket:
+    def __init__(self, headers: dict[str, str]):
+        self.headers = headers
+        self.accepted_subprotocol = None
+
+    async def accept(self, subprotocol=None):
+        self.accepted_subprotocol = subprotocol
+
+
+def test_handle_openai_responses_ws_resolves_codex_routing_headers():
+    class SentinelError(RuntimeError):
+        pass
+
+    handler = _DummyOpenAIHandler()
+    websocket = _DummyWebSocket({"authorization": "Bearer token"})
+
+    with patch.dict(sys.modules, {"websockets": MagicMock()}):
+        with patch(
+            "headroom.proxy.handlers.openai._resolve_codex_routing_headers",
+            side_effect=SentinelError("resolved"),
+        ):
+            with pytest.raises(SentinelError, match="resolved"):
+                anyio.run(handler.handle_openai_responses_ws, websocket)

tests/test_proxy_codex_route_aliases.py

@@ -0,0 +1,73 @@
+import httpx
+from fastapi import WebSocket
+from fastapi.responses import JSONResponse
+from fastapi.testclient import TestClient
+
+from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app
+
+
+def test_codex_responses_aliases_delegate_to_openai_handler(monkeypatch):
+    async def fake_handle(self, request):  # type: ignore[no-untyped-def]
+        return JSONResponse({"ok": True, "path": request.url.path})
+
+    monkeypatch.setattr(HeadroomProxy, "handle_openai_responses", fake_handle)
+
+    with TestClient(create_app(ProxyConfig())) as client:
+        for path in ("/backend-api/responses", "/backend-api/codex/responses"):
+            response = client.post(path, json={"model": "gpt-5.3-codex"})
+            assert response.status_code == 200
+            assert response.json() == {"ok": True, "path": path}
+
+
+def test_codex_responses_websocket_aliases_delegate_to_openai_handler(monkeypatch):
+    seen_paths: list[str] = []
+
+    async def fake_handle_ws(self, websocket: WebSocket):  # type: ignore[no-untyped-def]
+        seen_paths.append(websocket.url.path)
+        await websocket.accept()
+        await websocket.send_json({"ok": True, "path": websocket.url.path})
+        await websocket.close()
+
+    monkeypatch.setattr(HeadroomProxy, "handle_openai_responses_ws", fake_handle_ws)
+
+    with TestClient(create_app(ProxyConfig())) as client:
+        for path in ("/backend-api/responses", "/backend-api/codex/responses"):
+            with client.websocket_connect(path) as websocket:
+                assert websocket.receive_json() == {"ok": True, "path": path}
+
+    assert seen_paths == ["/backend-api/responses", "/backend-api/codex/responses"]
+
+
+def test_codex_responses_subpath_aliases_delegate_to_passthrough():
+    class FakeAsyncClient:
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str]] = []
+
+        async def request(self, method, url, **_kwargs):  # type: ignore[no-untyped-def]
+            self.calls.append((method, url))
+            return httpx.Response(200, json={"method": method, "url": url})
+
+        async def aclose(self) -> None:
+            return None
+
+    with TestClient(create_app(ProxyConfig())) as client:
+        fake_http_client = FakeAsyncClient()
+        client.app.state.proxy.http_client = fake_http_client
+        client.app.state.proxy.OPENAI_API_URL = "https://api.openai.test"
+
+        api_key_response = client.post(
+            "/backend-api/responses/compact?trace=1",
+            json={"model": "gpt-5.3-codex"},
+        )
+        chatgpt_response = client.post(
+            "/backend-api/codex/responses/compact?trace=2",
+            headers={"chatgpt-account-id": "acct_123"},
+            json={"model": "gpt-5.3-codex"},
+        )
+
+    assert api_key_response.status_code == 200
+    assert chatgpt_response.status_code == 200
+    assert fake_http_client.calls == [
+        ("POST", "https://api.openai.test/v1/responses/compact?trace=1"),
+        ("POST", "https://chatgpt.com/backend-api/codex/responses/compact?trace=2"),
+    ]