feat: add generic OpenAI-compatible endpoint provider

Add an openai_compatible provider so users can point at any
OpenAI-compatible Chat Completions server with a custom base URL
(server root or /v1) and a comma-separated API key pool. The profile
sends no reasoning params and parses /think tags; keys rotate
round-robin with failover on transient errors like every other
provider. Admin manifest gains key/base URL/proxy fields, smoke
override, and helpful descriptions. Bump to 4.20.0.

.env.example

@@ -11,6 +11,11 @@ AZURE_OPENAI_API_KEY=""
 AZURE_OPENAI_BASE_URL=""
 
 
+# Generic OpenAI-Compatible Endpoint (bring your own base URL; key accepts a comma-separated pool)
+OPENAI_COMPATIBLE_API_KEY=""
+OPENAI_COMPATIBLE_BASE_URL=""
+
+
 # OpenRouter Config
 OPENROUTER_API_KEY=""
 
@@ -125,7 +130,7 @@ OLLAMA_BASE_URL="http://localhost:11434"
 
 # All Claude model requests are mapped to these models, plain model is fallback
 # Format: provider_type/model/name
-# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "sambanova" | "kilo" | "fireworks" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama"
+# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "openai_compatible" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "sambanova" | "kilo" | "fireworks" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama"
 MODEL_FABLE=
 MODEL_OPUS=
 MODEL_SONNET=
@@ -139,6 +144,7 @@ FCC_SMOKE_MODEL_NVIDIA_NIM=
 FCC_SMOKE_MODEL_OPENAI=
 FCC_SMOKE_MODEL_AZURE_OPENAI=
 FCC_SMOKE_MODEL_OPEN_ROUTER=
+FCC_SMOKE_MODEL_OPENAI_COMPATIBLE=
 FCC_SMOKE_MODEL_MISTRAL=
 FCC_SMOKE_MODEL_MISTRAL_REASONING=
 FCC_SMOKE_MODEL_MISTRAL_CODESTRAL=
@@ -188,6 +194,7 @@ REASONING_HAIKU=inherit
 # Per-provider proxy support: http and socks5, example: "http://username:password@host:port"
 OPENAI_PROXY=""
 AZURE_OPENAI_PROXY=""
+OPENAI_COMPATIBLE_PROXY=""
 NVIDIA_NIM_PROXY=""
 OPENROUTER_PROXY=""
 MISTRAL_PROXY=""

README.md

@@ -155,6 +155,7 @@ fcc-codex exec "hello"
 | [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
 | [OpenAI / ChatGPT](https://learn.chatgpt.com/docs/auth) | Connect ChatGPT in the Admin UI | `openai/<model-id>` |
 | [Azure OpenAI](https://learn.microsoft.com/azure/foundry/openai/how-to/chatgpt) | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_BASE_URL` | `azure_openai/<deployment-name>` |
+| [OpenAI-Compatible Endpoint](https://platform.openai.com/docs/api-reference) | `OPENAI_COMPATIBLE_API_KEY` and `OPENAI_COMPATIBLE_BASE_URL` | `openai_compatible/<model-id>` |
 | [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
 | [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
 | [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` |
@@ -197,6 +198,11 @@ fcc-codex exec "hello"
   `https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/`, and select a
   deployment that supports Chat Completions. Enter the deployment name as a
   custom model slug if it does not appear in the model dropdown.
+- The generic OpenAI-Compatible Endpoint lets you point at your own Chat
+  Completions server. Set `OPENAI_COMPATIBLE_BASE_URL` to the server root
+  (for example `https://my-gateway.example`) or its `/v1` base, and
+  `OPENAI_COMPATIBLE_API_KEY` to a single key or a comma-separated key pool
+  that is rotated round-robin with failover like every other provider.
 - Mistral Codestral uses a separate key from Mistral La Plateforme.
 - Kimi Code subscription keys use `kimi_code/`; Kimi API credit keys use
   `kimi/`. Kimi Code plans are for personal interactive coding-agent use under

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "free-claude-code"
-version = "4.19.0"
+version = "4.20.0"
 description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
 readme = "README.md"
 requires-python = ">=3.14.0"

src/free_claude_code/config/admin/manifest.py

@@ -580,6 +580,12 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
         "smoke",
         advanced=True,
     ),
+    ConfigFieldSpec(
+        "FCC_SMOKE_MODEL_OPENAI_COMPATIBLE",
+        "Smoke OpenAI-Compatible Endpoint Model",
+        "smoke",
+        advanced=True,
+    ),
     ConfigFieldSpec(
         "FCC_SMOKE_MODEL_MISTRAL",
         "Smoke Mistral Model",

src/free_claude_code/config/admin/provider_manifest.py

@@ -22,6 +22,18 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
             "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/."
         ),
     },
+    "OPENAI_COMPATIBLE_API_KEY": {
+        "description": (
+            "API key for your OpenAI-compatible endpoint. Accepts a comma-separated "
+            "key pool that is rotated round-robin with failover on transient errors."
+        ),
+    },
+    "OPENAI_COMPATIBLE_BASE_URL": {
+        "description": (
+            "Base URL of your OpenAI-compatible Chat Completions server, for example "
+            "https://my-gateway.example or https://my-gateway.example/v1."
+        ),
+    },
     "NVIDIA_NIM_API_KEY": {
         "label": "NVIDIA NIM API Key",
         "description": "Used by NVIDIA NIM chat and optional NIM voice transcription.",

src/free_claude_code/config/provider_catalog.py

@@ -116,6 +116,20 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
             "azure_openai_base_url",
         ),
     ),
+    # Bring-your-own OpenAI-compatible Chat Completions endpoint. The customer
+    # owns the base URL; credentials accept a comma-separated key pool.
+    "openai_compatible": ProviderDescriptor(
+        provider_id="openai_compatible",
+        display_name="OpenAI-Compatible Endpoint",
+        credential_env="OPENAI_COMPATIBLE_API_KEY",
+        credential_attr="openai_compatible_api_key",
+        base_url_attr="openai_compatible_base_url",
+        proxy_attr="openai_compatible_proxy",
+        required_settings_attrs=(
+            "openai_compatible_api_key",
+            "openai_compatible_base_url",
+        ),
+    ),
     "open_router": ProviderDescriptor(
         provider_id="open_router",
         display_name="OpenRouter",

src/free_claude_code/config/settings.py

@@ -28,6 +28,15 @@ class Settings(BaseSettings):
         default="", validation_alias="AZURE_OPENAI_BASE_URL"
     )
 
+    # ==================== Generic OpenAI-Compatible Endpoint ====================
+    # Bring-your-own base URL; the key accepts a comma-separated pool.
+    openai_compatible_api_key: str = Field(
+        default="", validation_alias="OPENAI_COMPATIBLE_API_KEY"
+    )
+    openai_compatible_base_url: str = Field(
+        default="", validation_alias="OPENAI_COMPATIBLE_BASE_URL"
+    )
+
     # ==================== OpenRouter Config ====================
     open_router_api_key: str = Field(default="", validation_alias="OPENROUTER_API_KEY")
 
@@ -163,6 +172,9 @@ class Settings(BaseSettings):
     # ==================== Per-Provider Proxy ====================
     openai_proxy: str = Field(default="", validation_alias="OPENAI_PROXY")
     azure_openai_proxy: str = Field(default="", validation_alias="AZURE_OPENAI_PROXY")
+    openai_compatible_proxy: str = Field(
+        default="", validation_alias="OPENAI_COMPATIBLE_PROXY"
+    )
     nvidia_nim_proxy: str = Field(default="", validation_alias="NVIDIA_NIM_PROXY")
     open_router_proxy: str = Field(default="", validation_alias="OPENROUTER_PROXY")
     mistral_proxy: str = Field(default="", validation_alias="MISTRAL_PROXY")

src/free_claude_code/providers/openai_chat/profiles.py

@@ -152,6 +152,20 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
         ),
         model_ids_are_routable=False,
     ),
+    # Generic bring-your-own OpenAI-compatible Chat Completions endpoint.
+    # Send no reasoning params (many self-hosted servers reject unknown fields);
+    # THINK_TAGS replay still surfaces /think delimiters models emit. Accepts a
+    # server root or an explicit /v1 base, and passes caller extra_body through.
+    "openai_compatible": OpenAIChatProfile(
+        _policy(
+            "OPENAI_COMPATIBLE",
+            ReasoningReplayMode.THINK_TAGS,
+            include_extra_body=True,
+            extra_body_validator=validate_extra_body_does_not_override_canonical_fields,
+        ),
+        NO_REASONING,
+        normalize_base_url=True,
+    ),
     "mistral_codestral": OpenAIChatProfile(
         _policy("CODESTRAL", ReasoningReplayMode.THINK_TAGS),
         NO_REASONING,

tests/contracts/test_admin_provider_manifest.py

@@ -192,3 +192,39 @@ def test_azure_openai_admin_status_distinguishes_key_and_url() -> None:
         )["status"]
         == "configured"
     )
+
+
+def test_openai_compatible_admin_status_distinguishes_key_and_url() -> None:
+    from free_claude_code.config.admin.status import provider_config_status
+
+    def compatible_status(api_key: str, base_url: str) -> dict[str, object]:
+        statuses = provider_config_status(
+            {
+                "OPENAI_COMPATIBLE_API_KEY": {"value": api_key},
+                "OPENAI_COMPATIBLE_BASE_URL": {"value": base_url},
+            }
+        )
+        return next(
+            status
+            for status in statuses
+            if status["provider_id"] == "openai_compatible"
+        )
+
+    missing_key = compatible_status("", "https://my-gateway.example/v1")
+    assert missing_key["status"] == "missing_key"
+    assert missing_key["label"] == "Missing key"
+
+    missing_url = compatible_status("gateway-key", "")
+    assert missing_url["status"] == "missing_config"
+    assert missing_url["label"] == "Missing configuration"
+    assert missing_url["configuration"] == (
+        "OPENAI_COMPATIBLE_API_KEY + OPENAI_COMPATIBLE_BASE_URL"
+    )
+
+    assert (
+        compatible_status(
+            "gateway-key",
+            "https://my-gateway.example/v1",
+        )["status"]
+        == "configured"
+    )

tests/contracts/test_provider_catalog_order.py

@@ -9,6 +9,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
     "nvidia_nim",
     "openai",
     "azure_openai",
+    "openai_compatible",
     "open_router",
     "gemini",
     "vertex",

tests/providers/test_provider_runtime.py

@@ -55,6 +55,8 @@ def _make_settings(**overrides):
     mock.model_haiku = None
     mock.azure_openai_api_key = "test_azure_openai_key"
     mock.azure_openai_base_url = "https://test-resource.openai.azure.com/openai/v1/"
+    mock.openai_compatible_api_key = "test_openai_compatible_key"
+    mock.openai_compatible_base_url = "https://my-gateway.example/v1"
     mock.nvidia_nim_api_key = "test_key"
     mock.open_router_api_key = "test_openrouter_key"
     mock.mistral_api_key = "test_mistral_key"
@@ -113,6 +115,7 @@ def _make_settings(**overrides):
     mock.kilo_proxy = ""
     mock.openai_proxy = ""
     mock.azure_openai_proxy = ""
+    mock.openai_compatible_proxy = ""
     mock.provider_rate_limit = 40
     mock.provider_rate_window = 60
     mock.provider_max_concurrency = 5
@@ -234,6 +237,63 @@ def test_azure_openai_provider_config_reports_missing_resource_url() -> None:
         )
 
 
+def test_openai_compatible_provider_config_uses_custom_base_key_and_proxy() -> None:
+    descriptor = PROVIDER_CATALOG["openai_compatible"]
+    settings = _make_settings(
+        openai_compatible_api_key="gateway-1, gateway-2",
+        openai_compatible_base_url="https://my-gateway.example/v1",
+        openai_compatible_proxy="http://proxy.test:8080",
+    )
+
+    config = build_provider_config(descriptor, settings)
+
+    assert descriptor.default_base_url is None
+    assert descriptor.configuration_attrs() == (
+        "openai_compatible_api_key",
+        "openai_compatible_base_url",
+    )
+    assert config.api_key == "gateway-1"
+    assert config.api_keys == ("gateway-1", "gateway-2")
+    assert config.base_url == "https://my-gateway.example/v1"
+    assert config.proxy == "http://proxy.test:8080"
+
+
+def test_openai_compatible_provider_config_reports_missing_base_url() -> None:
+    descriptor = PROVIDER_CATALOG["openai_compatible"]
+
+    with pytest.raises(
+        ApplicationUnavailableError,
+        match="OPENAI_COMPATIBLE_BASE_URL is not set",
+    ):
+        build_provider_config(
+            descriptor,
+            _make_settings(
+                openai_compatible_api_key="gateway-token",
+                openai_compatible_base_url="",
+            ),
+        )
+
+
+def test_create_openai_compatible_provider_normalizes_base_url_and_pools_keys() -> None:
+    settings = _make_settings(
+        openai_compatible_api_key="k1, k2",
+        openai_compatible_base_url="https://my-gateway.example",
+    )
+
+    with patch(
+        "free_claude_code.providers.openai_chat.provider.AsyncOpenAI"
+    ) as client_cls:
+        provider = create_provider("openai_compatible", settings)
+
+    assert isinstance(provider, OpenAIChatProvider)
+    # Server root is normalized to the /v1 OpenAI-compatible base.
+    assert provider._base_url == "https://my-gateway.example/v1"
+    assert provider._provider_name == "OPENAI_COMPATIBLE"
+    assert provider._pool is not None
+    assert provider._pool.size == 2
+    assert client_cls.call_count == 2
+
+
 @pytest.mark.parametrize(
     ("provider_id", "expected_api_key"),
     [
@@ -472,6 +532,7 @@ def test_create_provider_instantiates_each_builtin():
         "nvidia_nim": NvidiaNimProvider,
         "openai": OpenAICodexProvider,
         "azure_openai": OpenAIChatProvider,
+        "openai_compatible": OpenAIChatProvider,
         "open_router": OpenRouterProvider,
         "mistral": MistralProvider,
         "mistral_codestral": OpenAIChatProvider,

uv.lock

@@ -620,7 +620,7 @@ wheels = [
 
 [[package]]
 name = "free-claude-code"
-version = "4.19.0"
+version = "4.20.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },