Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(openclaw): route codex through headroom proxy

JerrettDavis92b7b09f7021
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index a2eb3be34..cc1744d9c 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/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:
diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json
index e5b8bb865..682dcad5b 100644
--- a/plugins/openclaw/openclaw.plugin.json
+++ b/plugins/openclaw/openclaw.plugin.json
@@ -13,6 +13,10 @@
"pythonPath": {
"label": "Python Path",
"help": "Optional explicit python executable for python fallback launcher (for example: python, python3, py, or full path)."
+ },
+ "routeCodexViaProxy": {
+ "label": "Route OpenAI Codex Via Headroom",
+ "help": "When enabled, OpenClaw will use the active Headroom proxy as the upstream base URL for the built-in openai-codex provider so provider traffic flows through Headroom."
}
},
"configSchema": {
@@ -44,6 +48,10 @@
"minimum": 1000,
"maximum": 120000,
"default": 20000
+ },
+ "routeCodexViaProxy": {
+ "type": "boolean",
+ "default": true
}
}
},
diff --git a/plugins/openclaw/src/engine.ts b/plugins/openclaw/src/engine.ts
index 6511eee8e..c79e0b139 100644
--- a/plugins/openclaw/src/engine.ts
+++ b/plugins/openclaw/src/engine.ts
@@ -237,4 +237,13 @@ export class HeadroomContextEngine {
getProxyUrl(): string | null {
return this.proxyUrl;
}
+
+ async ensureProxyUrl(): Promise<string> {
+ if (this.proxyUrl) {
+ return this.proxyUrl;
+ }
+
+ this.proxyUrl = await this.proxyManager.start();
+ return this.proxyUrl;
+ }
}
diff --git a/plugins/openclaw/src/gateway-config.ts b/plugins/openclaw/src/gateway-config.ts
new file mode 100644
index 000000000..1ba00c2bc
--- /dev/null
+++ b/plugins/openclaw/src/gateway-config.ts
@@ -0,0 +1,60 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export const DEFAULT_GATEWAY_PROVIDER_IDS = ["openai-codex"] as const;
+
+export function resolveGatewayProviderIds(config: Record<string, unknown> | undefined): string[] {
+ if (config?.routeCodexViaProxy === false) {
+ return [];
+ }
+
+ return [...DEFAULT_GATEWAY_PROVIDER_IDS];
+}
+
+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 };
+
+ if (!Array.isArray(nextConfig.models)) {
+ nextConfig.models = [];
+ changed = true;
+ }
+
+ if (nextConfig.baseUrl === proxyUrl) {
+ providers[providerId] = nextConfig;
+ continue;
+ }
+
+ nextConfig.baseUrl = proxyUrl;
+ providers[providerId] = nextConfig;
+ changed = true;
+ }
+
+ return changed;
+}
diff --git a/plugins/openclaw/src/index.ts b/plugins/openclaw/src/index.ts
index 16a3ae2cd..96006224f 100644
--- a/plugins/openclaw/src/index.ts
+++ b/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";
diff --git a/plugins/openclaw/src/plugin/index.ts b/plugins/openclaw/src/plugin/index.ts
index 2c908f685..8f7d05e36 100644
--- a/plugins/openclaw/src/plugin/index.ts
+++ b/plugins/openclaw/src/plugin/index.ts
@@ -16,6 +16,11 @@
/* eslint-disable @typescript-eslint/no-explicit-any */
import { HeadroomContextEngine } from "../engine.js";
+import {
+ applyGatewayProviderBaseUrls,
+ applyGatewayProviderBaseUrlsInPlace,
+ resolveGatewayProviderIds,
+} from "../gateway-config.js";
import { normalizeAndValidateProxyUrl } from "../proxy-manager.js";
import { createHeadroomRetrieveTool } from "../tools/headroom-retrieve.js";
@@ -34,6 +39,47 @@ export default function headroomPlugin(api: any) {
error: (m: string) => logger.error(m),
debug: (m: string) => logger.debug?.(m),
});
+ const gatewayProviderIds = resolveGatewayProviderIds(config);
+
+ const ensureGatewayRouting = async () => {
+ if (gatewayProviderIds.length === 0) {
+ return;
+ }
+
+ try {
+ const activeProxyUrl = await engine.ensureProxyUrl();
+
+ applyGatewayProviderBaseUrlsInPlace(api.config, activeProxyUrl, gatewayProviderIds);
+
+ const currentConfig = api.runtime?.config?.loadConfig?.();
+ const writeConfigFile = api.runtime?.config?.writeConfigFile;
+ if (!currentConfig || typeof writeConfigFile !== "function") {
+ logger.info(
+ `[headroom] Upstream gateway routing active in memory for ${gatewayProviderIds.join(", ")} via ${activeProxyUrl}`,
+ );
+ return;
+ }
+
+ const { changed, config: nextConfig } = applyGatewayProviderBaseUrls(
+ currentConfig,
+ activeProxyUrl,
+ gatewayProviderIds,
+ );
+
+ if (changed) {
+ await writeConfigFile(nextConfig);
+ logger.info(
+ `[headroom] Routed ${gatewayProviderIds.join(", ")} through Headroom proxy at ${activeProxyUrl}`,
+ );
+ } else {
+ logger.info(
+ `[headroom] Upstream gateway already routed for ${gatewayProviderIds.join(", ")} at ${activeProxyUrl}`,
+ );
+ }
+ } catch (error) {
+ logger.warn(`[headroom] Failed to configure upstream gateway routing: ${error}`);
+ }
+ };
// Register as context engine
api.registerContextEngine("headroom", () => engine);
@@ -45,5 +91,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");
}
diff --git a/plugins/openclaw/test/gateway-config.test.ts b/plugins/openclaw/test/gateway-config.test.ts
new file mode 100644
index 000000000..9afbf5fd5
--- /dev/null
+++ b/plugins/openclaw/test/gateway-config.test.ts
@@ -0,0 +1,87 @@
+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 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",
+ models: [],
+ });
+ });
+
+ it("preserves existing provider config fields", () => {
+ const result = applyGatewayProviderBaseUrls(
+ {
+ models: {
+ providers: {
+ "openai-codex": {
+ api: "openai-codex-responses",
+ },
+ },
+ },
+ },
+ "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",
+ 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",
+ models: [],
+ },
+ },
+ },
+ };
+
+ const result = applyGatewayProviderBaseUrls(cfg, "http://127.0.0.1:8787", ["openai-codex"]);
+
+ expect(result.changed).toBe(false);
+ expect(result.config).toEqual(cfg);
+ });
+});
+
+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",
+ models: [],
+ });
+ });
+});
diff --git a/tests/test_openai_codex_routing.py b/tests/test_openai_codex_routing.py
new file mode 100644
index 000000000..bbdcb3e71
--- /dev/null
+++ b/tests/test_openai_codex_routing.py
@@ -0,0 +1,58 @@
+import base64
+import json
+
+from headroom.proxy.handlers.openai import _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