Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Repair invalid managed provider proxies at startup (#1586)

Ali Khokharaf59bc08b1f9
diff --git a/pyproject.toml b/pyproject.toml
index 2047eda6..ea33ca34 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.15.1"
+version = "5.15.2"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/cli/commands.py b/src/free_claude_code/cli/commands.py
index e5e45e94..4a16c676 100644
--- a/src/free_claude_code/cli/commands.py
+++ b/src/free_claude_code/cli/commands.py
@@ -6,10 +6,16 @@ import webbrowser
from enum import StrEnum
import uvicorn
+from loguru import logger
from free_claude_code.cli.launchers.common import preflight_proxy
from free_claude_code.cli.process_registry import kill_all_best_effort
-from free_claude_code.config.loader import clear_settings_cache, get_settings
+from free_claude_code.config.loader import (
+ clear_settings_cache,
+ get_settings,
+ repair_invalid_managed_provider_proxies,
+)
+from free_claude_code.config.paths import managed_env_path
from free_claude_code.config.server_urls import local_admin_url, local_proxy_root_url
from free_claude_code.config.settings import Settings
from free_claude_code.runtime.bootstrap import build_asgi_app
@@ -178,8 +184,20 @@ class ServerSupervisor:
def load_server_settings() -> Settings:
- """Return the canonical cached settings."""
-
+ """Return canonical settings after repairing invalid managed proxies."""
+
+ settings = get_settings()
+ removed = repair_invalid_managed_provider_proxies()
+ if not removed:
+ return settings
+
+ logger.warning(
+ "Removed invalid managed provider proxy settings from {}: {}. "
+ "Configure valid proxy URLs in Admin if needed.",
+ managed_env_path(),
+ ", ".join(removed),
+ )
+ clear_settings_cache()
return get_settings()
diff --git a/src/free_claude_code/config/admin/persistence.py b/src/free_claude_code/config/admin/persistence.py
index 014be7b4..851fa7cd 100644
--- a/src/free_claude_code/config/admin/persistence.py
+++ b/src/free_claude_code/config/admin/persistence.py
@@ -4,8 +4,6 @@ from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
-import httpx
-
from free_claude_code.config.env_files import (
FCC_CONFIG_SCHEMA_ENV,
dotenv_values_from_file,
@@ -17,7 +15,7 @@ from free_claude_code.config.env_migrations import (
render_managed_config,
)
from free_claude_code.config.paths import managed_env_path
-from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
+from free_claude_code.config.provider_proxies import invalid_provider_proxy_keys
from free_claude_code.config.settings import Settings
from free_claude_code.core.json_types import JsonObject
@@ -26,16 +24,6 @@ from .state import ConfigInputValue
from .validation import settings_from_values
from .values import MASKED_SECRET, is_locked_source, load_value_state, normalize_for_env
-_PROVIDER_PROXY_ATTRS = frozenset(
- descriptor.proxy_attr
- for descriptor in PROVIDER_CATALOG.values()
- if descriptor.proxy_attr is not None
-)
-_PROVIDER_PROXY_KEYS = tuple(
- field.key
- for field in FIELD_BY_KEY.values()
- if field.settings_attr in _PROVIDER_PROXY_ATTRS
-)
_PROVIDER_PROXY_ERROR = (
"must be a proxy URL with a supported scheme and host "
"(for example http://127.0.0.1:8080 or socks5://127.0.0.1:1080)"
@@ -210,19 +198,9 @@ def _update_protocol_errors(
def _provider_proxy_errors(values: Mapping[str, str]) -> tuple[str, ...]:
- errors: list[str] = []
- for key in _PROVIDER_PROXY_KEYS:
- value = values.get(key)
- if not value:
- continue
- try:
- proxy = httpx.Proxy(value)
- except httpx.InvalidURL, ValueError:
- errors.append(f"{key}: {_PROVIDER_PROXY_ERROR}")
- continue
- if not proxy.url.host:
- errors.append(f"{key}: {_PROVIDER_PROXY_ERROR}")
- return tuple(errors)
+ return tuple(
+ f"{key}: {_PROVIDER_PROXY_ERROR}" for key in invalid_provider_proxy_keys(values)
+ )
def _active_voice_credential(settings: Settings) -> str | None:
diff --git a/src/free_claude_code/config/loader.py b/src/free_claude_code/config/loader.py
index 183d92fb..05d0e683 100644
--- a/src/free_claude_code/config/loader.py
+++ b/src/free_claude_code/config/loader.py
@@ -10,8 +10,13 @@ from types import MappingProxyType
from free_claude_code.core.interprocess_lock import InterprocessFileLock
from .env_files import ANTHROPIC_AUTH_TOKEN_ENV, dotenv_values_from_file
-from .env_migrations import consolidate_managed_config, settings_env_keys
+from .env_migrations import (
+ atomic_write_managed_config,
+ consolidate_managed_config,
+ settings_env_keys,
+)
from .paths import config_lock_path, managed_env_path
+from .provider_proxies import invalid_provider_proxy_keys
from .settings import Settings
@@ -52,6 +57,40 @@ def resolve_settings_snapshot(
return compose_settings_snapshot(managed, process)
+def repair_invalid_managed_provider_proxies(
+ env: Mapping[str, str] | None = None,
+) -> tuple[str, ...]:
+ """Atomically remove invalid managed proxies not owned by the process."""
+
+ process = env if env is not None else os.environ
+ managed_path = managed_env_path()
+ if not managed_path.is_file():
+ return ()
+
+ lock = InterprocessFileLock(config_lock_path())
+ if not lock.acquire(wait=True, timeout=10.0):
+ raise TimeoutError(
+ f"Could not acquire managed-config lock: {config_lock_path()}"
+ )
+ try:
+ if not managed_path.is_file():
+ return ()
+ managed = dotenv_values_from_file(managed_path)
+ removed = tuple(
+ key for key in invalid_provider_proxy_keys(managed) if key not in process
+ )
+ if not removed:
+ return ()
+
+ repaired = dict(managed)
+ for key in removed:
+ repaired.pop(key)
+ atomic_write_managed_config(repaired, path=managed_path)
+ return removed
+ finally:
+ lock.release()
+
+
def compose_settings_snapshot(
managed: Mapping[str, str],
env: Mapping[str, str] | None = None,
diff --git a/src/free_claude_code/config/provider_proxies.py b/src/free_claude_code/config/provider_proxies.py
new file mode 100644
index 00000000..f1ea8094
--- /dev/null
+++ b/src/free_claude_code/config/provider_proxies.py
@@ -0,0 +1,44 @@
+"""Classification for provider proxies owned by the provider catalog."""
+
+from collections.abc import Mapping
+
+import httpx
+
+from .provider_catalog import PROVIDER_CATALOG
+from .settings import Settings
+
+
+def _provider_proxy_env_keys() -> tuple[str, ...]:
+ keys: list[str] = []
+ for descriptor in PROVIDER_CATALOG.values():
+ if descriptor.proxy_attr is None:
+ continue
+ field = Settings.model_fields[descriptor.proxy_attr]
+ alias = field.validation_alias
+ if not isinstance(alias, str):
+ raise AssertionError(
+ f"Settings field {descriptor.proxy_attr!r} needs one string alias"
+ )
+ keys.append(alias)
+ return tuple(keys)
+
+
+PROVIDER_PROXY_ENV_KEYS = _provider_proxy_env_keys()
+
+
+def invalid_provider_proxy_keys(values: Mapping[str, str]) -> tuple[str, ...]:
+ """Return catalog provider-proxy keys whose nonblank values are unusable."""
+
+ invalid: list[str] = []
+ for key in PROVIDER_PROXY_ENV_KEYS:
+ value = values.get(key, "").strip()
+ if not value:
+ continue
+ try:
+ proxy = httpx.Proxy(value)
+ except httpx.InvalidURL, ValueError:
+ invalid.append(key)
+ continue
+ if not proxy.url.host:
+ invalid.append(key)
+ return tuple(invalid)
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 3ca8c757..ae75ccd0 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -182,6 +182,145 @@ def test_serve_respects_admin_browser_setting(open_admin_browser: bool) -> None:
)
+def test_server_startup_repairs_invalid_managed_provider_proxy(
+ caplog: pytest.LogCaptureFixture,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from free_claude_code.cli import commands
+ from free_claude_code.config.env_files import dotenv_values_from_file
+ from free_claude_code.config.paths import managed_env_path
+
+ monkeypatch.delenv("OPENAI_PROXY", raising=False)
+ invalid_proxy = "invalid://user:[email protected]:8080"
+ managed = managed_env_path()
+ managed.parent.mkdir(parents=True)
+ managed.write_text(
+ "\n".join(
+ (
+ "FCC_CONFIG_SCHEMA=1",
+ "MODEL=nvidia_nim/test-model",
+ f"OPENAI_PROXY={invalid_proxy}",
+ "",
+ )
+ ),
+ encoding="utf-8",
+ )
+ handed_off_settings: list[Settings] = []
+
+ def run_once(
+ _self: commands.ServerSupervisor,
+ settings: Settings,
+ *,
+ open_admin_browser: bool,
+ restart_generation: int,
+ ) -> bool:
+ assert open_admin_browser is False
+ assert restart_generation == 0
+ handed_off_settings.append(settings)
+ return False
+
+ with (
+ caplog.at_level("WARNING"),
+ patch.object(commands.ServerSupervisor, "_run_once", run_once),
+ patch.object(commands, "kill_all_best_effort"),
+ ):
+ commands.ServerSupervisor().run(open_admin_browser=False)
+
+ assert len(handed_off_settings) == 1
+ assert handed_off_settings[0].openai_proxy is None
+ assert "OPENAI_PROXY" not in dotenv_values_from_file(managed)
+ assert "OPENAI_PROXY" in caplog.text
+ assert invalid_proxy not in caplog.text
+ assert "leaked-secret" not in caplog.text
+
+
+def test_load_server_settings_skips_reload_when_no_repair_occurs(
+ caplog: pytest.LogCaptureFixture,
+) -> None:
+ from free_claude_code.cli import commands
+
+ settings = _launcher_settings()
+ with (
+ caplog.at_level("WARNING"),
+ patch.object(commands, "get_settings", return_value=settings) as get_settings,
+ patch.object(
+ commands,
+ "repair_invalid_managed_provider_proxies",
+ return_value=(),
+ ) as repair,
+ patch.object(commands, "clear_settings_cache") as clear_cache,
+ ):
+ loaded = commands.load_server_settings()
+
+ assert loaded is settings
+ get_settings.assert_called_once_with()
+ repair.assert_called_once_with()
+ clear_cache.assert_not_called()
+ assert "Removed invalid managed provider proxy settings" not in caplog.text
+
+
+def test_load_server_settings_reloads_once_and_warns_after_repair(
+ caplog: pytest.LogCaptureFixture,
+) -> None:
+ from free_claude_code.cli import commands
+ from free_claude_code.config.paths import managed_env_path
+
+ invalid_proxy = "invalid://user:[email protected]:8080"
+ stale = Settings(openai_proxy=invalid_proxy)
+ repaired = Settings()
+ get_settings = MagicMock(side_effect=(stale, repaired))
+
+ with (
+ caplog.at_level("WARNING"),
+ patch.object(commands, "get_settings", get_settings),
+ patch.object(
+ commands,
+ "repair_invalid_managed_provider_proxies",
+ return_value=("OPENAI_PROXY", "GROQ_PROXY"),
+ ),
+ patch.object(commands, "clear_settings_cache") as clear_cache,
+ ):
+ loaded = commands.load_server_settings()
+
+ assert loaded is repaired
+ assert get_settings.call_count == 2
+ clear_cache.assert_called_once_with()
+ warning = next(
+ record.message
+ for record in caplog.records
+ if "Removed invalid managed provider proxy settings" in record.message
+ )
+ assert str(managed_env_path()) in warning
+ assert "OPENAI_PROXY, GROQ_PROXY" in warning
+ assert invalid_proxy not in warning
+ assert "leaked-secret" not in warning
+
+
+def test_load_server_settings_leaves_process_owned_invalid_proxy_explicit(
+ caplog: pytest.LogCaptureFixture,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from free_claude_code.cli import commands
+ from free_claude_code.config.paths import managed_env_path
+
+ process_proxy = "invalid://process-proxy"
+ monkeypatch.setenv("OPENAI_PROXY", process_proxy)
+ managed = managed_env_path()
+ managed.parent.mkdir(parents=True)
+ managed.write_text(
+ "FCC_CONFIG_SCHEMA=1\nOPENAI_PROXY=invalid://managed-proxy\n",
+ encoding="utf-8",
+ )
+ baseline = managed.read_bytes()
+
+ with caplog.at_level("WARNING"):
+ settings = commands.load_server_settings()
+
+ assert settings.openai_proxy == process_proxy
+ assert managed.read_bytes() == baseline
+ assert "Removed invalid managed provider proxy settings" not in caplog.text
+
+
def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
from free_claude_code.cli import commands
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index 3f4c8266..d12edcc6 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -1,20 +1,25 @@
"""Contracts for pure Settings and canonical source composition."""
from enum import Enum
+from pathlib import Path
+from unittest.mock import patch
import pytest
from pydantic import ValidationError
from free_claude_code.application.routing import ModelRouter
+from free_claude_code.config import loader
from free_claude_code.config.constants import (
ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
HTTP_CONNECT_TIMEOUT_DEFAULT,
)
+from free_claude_code.config.env_files import dotenv_values_from_file
from free_claude_code.config.loader import (
ConfigSource,
clear_settings_cache,
compose_settings_snapshot,
get_settings,
+ repair_invalid_managed_provider_proxies,
)
from free_claude_code.config.model_refs import (
configured_chat_model_refs,
@@ -22,7 +27,11 @@ from free_claude_code.config.model_refs import (
parse_provider_type,
)
from free_claude_code.config.nim import NimSettings
-from free_claude_code.config.paths import messaging_state_dir_path, server_log_path
+from free_claude_code.config.paths import (
+ managed_env_path,
+ messaging_state_dir_path,
+ server_log_path,
+)
from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.config.settings import Settings
@@ -191,6 +200,153 @@ def test_get_settings_is_cached_and_creates_managed_schema() -> None:
assert first is second
+def _write_managed_config(text: str) -> Path:
+ path = managed_env_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+ return path
+
+
+def test_repair_invalid_managed_provider_proxies_removes_all_eligible_values() -> None:
+ invalid_openai = "invalid://user:[email protected]:8080"
+ managed = _write_managed_config(
+ "\n".join(
+ (
+ "FCC_CONFIG_SCHEMA=1",
+ "MODEL=nvidia_nim/test-model",
+ "OPENROUTER_PROXY=http://proxy.example:notaport",
+ "GROQ_PROXY=https://proxy.example:8443",
+ f"OPENAI_PROXY={invalid_openai}",
+ "PRESERVE_UNKNOWN=present",
+ "",
+ )
+ )
+ )
+
+ removed = repair_invalid_managed_provider_proxies({})
+
+ values = dotenv_values_from_file(managed)
+ assert removed == ("OPENROUTER_PROXY", "OPENAI_PROXY")
+ assert "OPENROUTER_PROXY" not in values
+ assert "OPENAI_PROXY" not in values
+ assert values["GROQ_PROXY"] == "https://proxy.example:8443"
+ assert values["MODEL"] == "nvidia_nim/test-model"
+ assert values["PRESERVE_UNKNOWN"] == "present"
+ assert list(managed.parent.glob(f".{managed.name}.*.tmp")) == []
+
+
+def test_repair_valid_managed_provider_proxy_leaves_file_unchanged() -> None:
+ managed = _write_managed_config(
+ "# Keep this exact text on a no-op.\n"
+ "FCC_CONFIG_SCHEMA=1\n"
+ "OPENAI_PROXY=https://proxy.example:8443\n"
+ )
+ baseline = managed.read_bytes()
+
+ assert repair_invalid_managed_provider_proxies({}) == ()
+ assert managed.read_bytes() == baseline
+
+
+def test_repair_without_managed_file_is_a_noop() -> None:
+ managed = managed_env_path()
+
+ assert repair_invalid_managed_provider_proxies({}) == ()
+ assert not managed.exists()
+
+
[email protected]("process_value", ("", "invalid://process-proxy"))
+def test_repair_preserves_process_owned_managed_proxy(
+ process_value: str,
+) -> None:
+ invalid_openai = "invalid://managed-proxy"
+ managed = _write_managed_config(
+ "FCC_CONFIG_SCHEMA=1\n"
+ f"OPENAI_PROXY={invalid_openai}\n"
+ "OPENROUTER_PROXY=invalid://unshadowed\n"
+ )
+ process = {"OPENAI_PROXY": process_value, "KEEP_PROCESS": "unchanged"}
+ baseline_process = dict(process)
+
+ assert repair_invalid_managed_provider_proxies(process) == ("OPENROUTER_PROXY",)
+
+ values = dotenv_values_from_file(managed)
+ assert values["OPENAI_PROXY"] == invalid_openai
+ assert "OPENROUTER_PROXY" not in values
+ assert process == baseline_process
+
+
+def test_repair_propagates_atomic_write_failure_without_changing_source() -> None:
+ managed = _write_managed_config(
+ "FCC_CONFIG_SCHEMA=1\nOPENAI_PROXY=invalid://managed-proxy\n"
+ )
+ baseline = managed.read_bytes()
+
+ with (
+ patch.object(
+ loader,
+ "atomic_write_managed_config",
+ side_effect=OSError("disk full"),
+ ),
+ pytest.raises(OSError, match="disk full"),
+ ):
+ repair_invalid_managed_provider_proxies({})
+
+ assert managed.read_bytes() == baseline
+
+
+def test_repair_is_idempotent_and_writes_only_once() -> None:
+ managed = _write_managed_config(
+ "FCC_CONFIG_SCHEMA=1\nOPENAI_PROXY=invalid://managed-proxy\n"
+ )
+
+ with patch.object(
+ loader,
+ "atomic_write_managed_config",
+ wraps=loader.atomic_write_managed_config,
+ ) as writer:
+ assert repair_invalid_managed_provider_proxies({}) == ("OPENAI_PROXY",)
+ repaired = managed.read_bytes()
+ assert repair_invalid_managed_provider_proxies({}) == ()
+
+ assert writer.call_count == 1
+ assert managed.read_bytes() == repaired
+
+
+def test_repair_propagates_malformed_managed_config() -> None:
+ managed = _write_managed_config('FCC_CONFIG_SCHEMA=1\nOPENAI_PROXY="unterminated\n')
+ baseline = managed.read_bytes()
+
+ with pytest.raises(ValueError, match="Could not parse configuration file"):
+ repair_invalid_managed_provider_proxies({})
+
+ assert managed.read_bytes() == baseline
+
+
+def test_repair_propagates_config_lock_timeout(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ managed = _write_managed_config(
+ "FCC_CONFIG_SCHEMA=1\nOPENAI_PROXY=invalid://managed-proxy\n"
+ )
+ baseline = managed.read_bytes()
+
+ class UnavailableLock:
+ def __init__(self, _path: Path) -> None:
+ pass
+
+ def acquire(self, *, wait: bool, timeout: float) -> bool:
+ assert wait is True
+ assert timeout == 10.0
+ return False
+
+ monkeypatch.setattr(loader, "InterprocessFileLock", UnavailableLock)
+
+ with pytest.raises(TimeoutError, match="Could not acquire managed-config lock"):
+ repair_invalid_managed_provider_proxies({})
+
+ assert managed.read_bytes() == baseline
+
+
def test_optional_strings_share_one_normalization_rule() -> None:
settings = Settings.model_validate(
{
diff --git a/uv.lock b/uv.lock
index 1ac8ecb5..95b5f434 100644
--- a/uv.lock
+++ b/uv.lock
@@ -607,7 +607,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.15.1"
+version = "5.15.2"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },