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

fix(codex): select the model slug the generated catalog advertises (#1564)

rodricksz4h5aa5f9bc7fb58
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 320eb004..c0ceca4b 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1332,6 +1332,9 @@ client environment.
`model_catalog_json` file under `~/.fcc/`, and injects that path so Codex's
native `/model` picker lists FCC provider slugs. Catalog generation is
fail-open: launch continues with a warning if the catalog cannot be prepared.
+- When the catalog projects the configured provider reference under a different
+ wire slug, `fcc-codex` selects that advertised slug. Failed, empty, or
+ incomplete discovery leaves the configured provider reference unchanged.
- The server lifecycle independently keeps that same file synchronized for
Codex App and IDE processes that are not launched through `fcc-codex`.
- Launcher-side catalog discovery authenticates directly with the canonical proxy
diff --git a/pyproject.toml b/pyproject.toml
index 3947a249..488a07ef 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.14.9"
+version = "5.14.10"
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/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.py
index dfb07186..ecaaa6eb 100644
--- a/src/free_claude_code/cli/launchers/codex.py
+++ b/src/free_claude_code/cli/launchers/codex.py
@@ -4,6 +4,7 @@ import json
import os
import sys
from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
from free_claude_code.cli.local_http import with_local_proxy_bypass
from free_claude_code.config.loader import get_settings
@@ -17,7 +18,12 @@ from .common import (
resolve_client_binary,
run_client_process,
)
-from .model_catalog import fetch_proxy_models_response
+from .model_catalog import (
+ ClientModel,
+ catalog_wire_slug_for_ref,
+ client_models_from_response,
+ fetch_proxy_models_response,
+)
_PRINT_PROXY_AUTH_TOKEN_FLAG = "--print-proxy-auth-token"
_DISPLAY_NAME = "Codex CLI"
@@ -64,14 +70,15 @@ def launch(argv: Sequence[str] | None = None) -> None:
display_name=_DISPLAY_NAME,
install_hint=_INSTALL_HINT,
)
- catalog_args = codex_model_catalog_config_args(proxy_root_url, settings)
+ catalog = codex_model_catalog_plan(proxy_root_url, settings)
run_client_process(
command=build_codex_launcher_command(
binary_path=binary_path,
argv=args,
settings=settings,
proxy_root_url=proxy_root_url,
- catalog_config_args=catalog_args,
+ catalog_config_args=catalog.config_args,
+ catalog_models=catalog.models,
),
env=build_codex_launcher_env(
proxy_root_url=proxy_root_url,
@@ -83,6 +90,14 @@ def launch(argv: Sequence[str] | None = None) -> None:
)
+@dataclass(frozen=True, slots=True)
+class CodexModelCatalogPlan:
+ """The generated Codex catalog config args and the models it advertises."""
+
+ config_args: tuple[str, ...] = ()
+ models: tuple[ClientModel, ...] = ()
+
+
def codex_binary_name() -> str:
"""Return the Codex CLI binary name."""
@@ -96,6 +111,7 @@ def build_codex_launcher_command(
settings: Settings,
proxy_root_url: str,
catalog_config_args: Sequence[str] = (),
+ catalog_models: Sequence[ClientModel] = (),
) -> list[str]:
"""Return a Codex command with ephemeral FCC provider config."""
@@ -104,7 +120,9 @@ def build_codex_launcher_command(
*catalog_config_args,
*codex_config_args(
api_url=_ensure_v1_url(proxy_root_url),
- model=getattr(settings, "model", None),
+ model=catalog_wire_slug_for_ref(
+ catalog_models, getattr(settings, "model", None)
+ ),
),
*argv,
]
@@ -128,35 +146,39 @@ def build_codex_launcher_env(
return env
-def codex_model_catalog_config_args(
+def codex_model_catalog_plan(
proxy_root_url: str, settings: Settings
-) -> list[str]:
- """Prepare the generated Codex model catalog and return its config args."""
+) -> CodexModelCatalogPlan:
+ """Prepare the generated Codex model catalog and the models it advertises."""
try:
models_response = fetch_proxy_models_response(
proxy_root_url, settings.proxy_auth_token
)
- catalog = build_codex_model_catalog(models_response)
- models = catalog.get("models")
- if not isinstance(models, list) or not models:
+ models = client_models_from_response(models_response)
+ if not models:
print(
"Free Claude Code warning: Codex model catalog is empty; "
"launching without model picker catalog.",
file=sys.stderr,
)
- return []
+ return CodexModelCatalogPlan()
catalog_path = codex_model_catalog_path()
- write_codex_model_catalog(catalog_path, catalog)
+ write_codex_model_catalog(
+ catalog_path, build_codex_model_catalog(models_response)
+ )
except Exception as exc:
print(
"Free Claude Code warning: could not prepare Codex model catalog "
f"({exc}); launching without model picker catalog.",
file=sys.stderr,
)
- return []
+ return CodexModelCatalogPlan()
- return build_model_catalog_config_args(str(catalog_path))
+ return CodexModelCatalogPlan(
+ config_args=tuple(build_model_catalog_config_args(str(catalog_path))),
+ models=models,
+ )
def build_model_catalog_config_args(catalog_path: str) -> list[str]:
diff --git a/src/free_claude_code/cli/launchers/model_catalog.py b/src/free_claude_code/cli/launchers/model_catalog.py
index 21ad4781..9f1c865c 100644
--- a/src/free_claude_code/cli/launchers/model_catalog.py
+++ b/src/free_claude_code/cli/launchers/model_catalog.py
@@ -1,7 +1,7 @@
"""Shared FCC model-catalog projection for installed client launchers."""
import json
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from urllib.request import Request
@@ -38,6 +38,26 @@ def client_models_from_response(
return tuple(models)
+def catalog_wire_slug_for_ref(
+ models: Sequence[ClientModel],
+ provider_model_ref: str | None,
+) -> str | None:
+ """Return the slug a client catalog advertises for one configured ref.
+
+ A model the gateway reports as non-thinking is advertised under its
+ no-thinking slug, not its bare provider ref, so a client told to select the
+ bare ref would not find it in the catalog it was given.
+ """
+
+ if not provider_model_ref:
+ return provider_model_ref
+
+ for model in models:
+ if model.provider_model_ref == provider_model_ref:
+ return model.wire_slug
+ return provider_model_ref
+
+
def fetch_proxy_models_response(proxy_root_url: str, auth_token: str) -> JsonObject:
"""Fetch the authenticated FCC-local `/v1/models` response directly."""
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index db1dcc6f..6bb336db 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -490,6 +490,177 @@ def test_launch_codex_passes_responses_config_and_child_env(
unregister_pid.assert_called_once_with(12345)
+def test_launch_codex_selects_the_slug_its_catalog_advertises(
+ tmp_path: Path,
+ empty_proxy_bypass_env: None,
+) -> None:
+ """A non-thinking configured model is advertised under its no-thinking slug."""
+
+ from free_claude_code.cli.launchers.codex import launch
+
+ settings = _launcher_settings(port=9191, token="proxy-token")
+ catalog_path = tmp_path / "codex-model-catalog.json"
+ no_thinking_slug = "claude-3-freecc-no-thinking/nvidia_nim/test-model"
+
+ def fake_urlopen(request: Request, *, timeout: float) -> _JsonResponse:
+ del request, timeout
+ return _JsonResponse(
+ {
+ "data": [
+ {
+ "id": no_thinking_slug,
+ "provider_model_ref": "nvidia_nim/test-model",
+ "display_name": "NVIDIA model (no thinking)",
+ }
+ ]
+ }
+ )
+
+ with (
+ patch(
+ "free_claude_code.cli.launchers.codex.get_settings", return_value=settings
+ ),
+ patch(
+ "free_claude_code.cli.launchers.codex.preflight_proxy", return_value=None
+ ),
+ patch(
+ "free_claude_code.cli.launchers.common.shutil.which",
+ return_value="resolved-codex.cmd",
+ ),
+ patch(
+ "free_claude_code.cli.launchers.codex.codex_model_catalog_path",
+ return_value=catalog_path,
+ ),
+ patch(
+ "free_claude_code.cli.launchers.model_catalog.open_local_request",
+ side_effect=fake_urlopen,
+ ),
+ patch("free_claude_code.cli.launchers.common.subprocess.Popen") as popen,
+ patch("free_claude_code.cli.launchers.common.register_pid"),
+ patch("free_claude_code.cli.launchers.common.unregister_pid"),
+ pytest.raises(SystemExit),
+ ):
+ process = popen.return_value
+ process.pid = 12345
+ process.wait.return_value = 0
+ launch(["exec", "hello"])
+
+ command = popen.call_args.args[0]
+ catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
+ assert [model["slug"] for model in catalog["models"]] == [no_thinking_slug]
+ assert f"model={json.dumps(no_thinking_slug)}" in command
+ assert 'model="nvidia_nim/test-model"' not in command
+
+
+def test_launch_codex_keeps_the_configured_ref_without_a_catalog(
+ tmp_path: Path,
+ empty_proxy_bypass_env: None,
+) -> None:
+ """A failed catalog fetch must not change the model Codex is told to use."""
+
+ from free_claude_code.cli.launchers.codex import launch
+
+ settings = _launcher_settings(port=9191, token="proxy-token")
+
+ with (
+ patch(
+ "free_claude_code.cli.launchers.codex.get_settings", return_value=settings
+ ),
+ patch(
+ "free_claude_code.cli.launchers.codex.preflight_proxy", return_value=None
+ ),
+ patch(
+ "free_claude_code.cli.launchers.common.shutil.which",
+ return_value="resolved-codex.cmd",
+ ),
+ patch(
+ "free_claude_code.cli.launchers.codex.codex_model_catalog_path",
+ return_value=tmp_path / "codex-model-catalog.json",
+ ),
+ patch(
+ "free_claude_code.cli.launchers.model_catalog.open_local_request",
+ side_effect=URLError("boom"),
+ ),
+ patch("free_claude_code.cli.launchers.common.subprocess.Popen") as popen,
+ patch("free_claude_code.cli.launchers.common.register_pid"),
+ patch("free_claude_code.cli.launchers.common.unregister_pid"),
+ pytest.raises(SystemExit),
+ ):
+ process = popen.return_value
+ process.pid = 12345
+ process.wait.return_value = 0
+ launch(["exec", "hello"])
+
+ assert 'model="nvidia_nim/test-model"' in popen.call_args.args[0]
+
+
+def test_codex_empty_catalog_keeps_the_configured_ref_without_catalog_config(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from free_claude_code.cli.launchers import codex
+
+ settings = _launcher_settings(port=9191, token="proxy-token")
+ with (
+ patch.object(codex, "fetch_proxy_models_response", return_value={"data": []}),
+ patch.object(codex, "write_codex_model_catalog") as write_catalog,
+ ):
+ catalog = codex.codex_model_catalog_plan("http://127.0.0.1:9191", settings)
+
+ command = codex.build_codex_launcher_command(
+ binary_path="resolved-codex.cmd",
+ argv=("exec", "hello"),
+ settings=settings,
+ proxy_root_url="http://127.0.0.1:9191",
+ catalog_config_args=catalog.config_args,
+ catalog_models=catalog.models,
+ )
+
+ assert catalog == codex.CodexModelCatalogPlan()
+ assert not any("model_catalog_json=" in arg for arg in command)
+ assert 'model="nvidia_nim/test-model"' in command
+ write_catalog.assert_not_called()
+ assert "Codex model catalog is empty" in capsys.readouterr().err
+
+
+ "failing_step", ("build_codex_model_catalog", "write_codex_model_catalog")
+)
+def test_codex_catalog_plan_fails_open_when_catalog_processing_fails(
+ failing_step: str,
+ capsys: pytest.CaptureFixture[str],
+ tmp_path: Path,
+) -> None:
+ from free_claude_code.cli.launchers import codex
+
+ settings = _launcher_settings(port=9191, token="proxy-token")
+ models_response = {
+ "data": [
+ {
+ "id": "nvidia_nim/test-model",
+ "provider_model_ref": "nvidia_nim/test-model",
+ "display_name": "NVIDIA model",
+ }
+ ]
+ }
+ with (
+ patch.object(
+ codex, "fetch_proxy_models_response", return_value=models_response
+ ),
+ patch.object(
+ codex,
+ "codex_model_catalog_path",
+ return_value=tmp_path / "codex-model-catalog.json",
+ ),
+ patch.object(codex, failing_step, side_effect=OSError("boom")),
+ ):
+ catalog = codex.codex_model_catalog_plan("http://127.0.0.1:9191", settings)
+
+ assert catalog == codex.CodexModelCatalogPlan()
+ captured = capsys.readouterr()
+ assert "could not prepare Codex model catalog" in captured.err
+ assert "launching without model picker catalog" in captured.err
+
+
def test_codex_proxy_auth_command_prints_only_current_token(
capsys: pytest.CaptureFixture[str],
) -> None:
diff --git a/tests/cli/test_model_catalog.py b/tests/cli/test_model_catalog.py
index 89b438f0..65defbdf 100644
--- a/tests/cli/test_model_catalog.py
+++ b/tests/cli/test_model_catalog.py
@@ -4,6 +4,7 @@ import pytest
from free_claude_code.cli.launchers.model_catalog import (
ClientModel,
+ catalog_wire_slug_for_ref,
client_models_from_response,
fetch_proxy_models_response,
)
@@ -169,3 +170,54 @@ def test_fetch_proxy_models_rejects_non_object_json() -> None:
pytest.raises(ValueError, match="JSON object"),
):
fetch_proxy_models_response("http://127.0.0.1:9191", "proxy-token")
+
+
+def _client_model(wire_slug: str, provider_model_ref: str) -> ClientModel:
+ return ClientModel(
+ wire_slug=wire_slug,
+ provider_model_ref=provider_model_ref,
+ display_name=provider_model_ref,
+ allows_reasoning=wire_slug == provider_model_ref,
+ )
+
+
+def test_catalog_wire_slug_prefers_the_advertised_no_thinking_slug() -> None:
+ models = (
+ _client_model(
+ "claude-3-freecc-no-thinking/open_router/vendor/chat-model",
+ "open_router/vendor/chat-model",
+ ),
+ )
+
+ assert (
+ catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
+ == "claude-3-freecc-no-thinking/open_router/vendor/chat-model"
+ )
+
+
+def test_catalog_wire_slug_keeps_a_directly_advertised_ref() -> None:
+ models = (
+ _client_model("open_router/vendor/chat-model", "open_router/vendor/chat-model"),
+ )
+
+ assert (
+ catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
+ == "open_router/vendor/chat-model"
+ )
+
+
+def test_catalog_wire_slug_falls_back_when_the_catalog_omits_the_ref() -> None:
+ models = (_client_model("open_router/vendor/other", "open_router/vendor/other"),)
+
+ assert (
+ catalog_wire_slug_for_ref(models, "open_router/vendor/chat-model")
+ == "open_router/vendor/chat-model"
+ )
+ assert catalog_wire_slug_for_ref((), "open_router/vendor/chat-model") == (
+ "open_router/vendor/chat-model"
+ )
+
+
+def test_catalog_wire_slug_passes_through_an_unset_model() -> None:
+ assert catalog_wire_slug_for_ref((), None) is None
+ assert catalog_wire_slug_for_ref((), "") == ""
diff --git a/uv.lock b/uv.lock
index 927b14fc..19779d03 100644
--- a/uv.lock
+++ b/uv.lock
@@ -607,7 +607,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.14.9"
+version = "5.14.10"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },