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(proxy): add fast-fail launch settings

JerrettDavisd4f6e3938f3e
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 306fb06ec..d036ffb6c 100644
--- a/headroom/cli/proxy.py
+++ b/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")
+ "--retry-max-attempts",
+ type=int,
+ default=None,
+ help="Maximum upstream retry attempts for connect/read/5xx failures (default: 3)",
+)
+ "--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)
diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json
index 50ddae626..1f055e2e8 100644
--- a/plugins/openclaw/openclaw.plugin.json
+++ b/plugins/openclaw/openclaw.plugin.json
@@ -14,6 +14,14 @@
"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."
@@ -53,6 +61,14 @@
"maximum": 120000,
"default": 20000
},
+ "retryMaxAttempts": {
+ "type": "integer",
+ "minimum": 1
+ },
+ "connectTimeoutSeconds": {
+ "type": "integer",
+ "minimum": 1
+ },
"routeCodexViaProxy": {
"type": "boolean",
"default": true
diff --git a/plugins/openclaw/src/proxy-manager.ts b/plugins/openclaw/src/proxy-manager.ts
index 76bddc160..14fdc1e72 100644
--- a/plugins/openclaw/src/proxy-manager.ts
+++ b/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 {
@@ -210,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
diff --git a/plugins/openclaw/test/proxy-manager.test.ts b/plugins/openclaw/test/proxy-manager.test.ts
index 16ff95b35..6af995e42 100644
--- a/plugins/openclaw/test/proxy-manager.test.ts
+++ b/plugins/openclaw/test/proxy-manager.test.ts
@@ -221,6 +221,24 @@ describe("ProxyManager launch internals", () => {
}
});
+ 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>>;
diff --git a/tests/test_cli_proxy_env.py b/tests/test_cli_proxy_env.py
index fc92d977d..121569e52 100644
--- a/tests/test_cli_proxy_env.py
+++ b/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."""