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

patch: Add OrcaRouter as an AI provider (#1754)

Tanishq-110fb1d02a180
diff --git a/README.md b/README.md
index 1c48940b..9e85fc0f 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@
## What You Get
-- **55 ToS-friendly providers. 1.3B+ free tokens every month.** Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. FCC follows provider terms and removes integrations if they stop being allowed.
+- **56 ToS-friendly providers. 1.3B+ free tokens every month.** Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. FCC follows provider terms and removes integrations if they stop being allowed.
- **11 coding agents. One model catalog.** Run [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [OpenCode](https://github.com/anomalyco/opencode), [Cline](https://github.com/cline/cline), [Hermes](https://github.com/NousResearch/hermes-agent), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [Grok Build](https://github.com/xai-org/grok-build), [Muse Code](https://research.meta.ai/blog/introducing-muse-code-and-muse-spark-1-2/), [Aider](https://aider.chat/), or [VS Code Chat](https://code.visualstudio.com/) with your FCC models.
- **Keep coding through provider outages.** After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn. This works across every client.
- **Up to 90% fewer terminal-output tokens.** Optional [RTK](https://github.com/rtk-ai/rtk) filters common command output, while five FCC optimizations handle quota probes, command-prefix detection, titles, suggestions, and filepaths without calling a provider.
@@ -256,6 +256,7 @@ For another API endpoint, open **Providers → Custom providers → Add provider
| [Lightning AI](https://lightning.ai/) | `LIGHTNING_API_KEY` | `lightning/lightning-ai/Qwen3.8-27B` |
| [Experiential Labs](https://platform.experientiallabs.ai/) | `EXPLABS_API_KEY` | `experiential/union-alpha` |
| [Cheaper Inference](https://cheaperinference.com/signup) | `CHEAPER_INFERENCE_API_KEY` | `cheaperinference/gpt-5.4-mini` |
+| [OrcaRouter](https://www.orcarouter.ai/) | `ORCAROUTER_API_KEY` | `orcarouter/deepseek/deepseek-v4-flash-free` |
| [Ollama Cloud](https://ollama.com/settings/keys) | `OLLAMA_API_KEY` | `ollama_cloud/qwen3-coder:480b` |
| [LM Studio](https://lmstudio.ai/) | `LM_STUDIO_BASE_URL` | `lmstudio/<model-id>` |
| [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/<model-id>` |
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 594d52f1..3b00005d 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -96,6 +96,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"lightning": "lightning/lightning-ai/Qwen3.8-27B",
"experiential": "experiential/union-alpha",
"cheaperinference": "cheaperinference/gpt-5.4-mini",
+ "orcarouter": "orcarouter/deepseek/deepseek-v4-flash-free",
"agnes": "agnes/agnes-2.0-flash",
"zenmux": "zenmux/deepseek/deepseek-v4-flash-free",
"wandb": "wandb/openai/gpt-oss-20b",
diff --git a/src/free_claude_code/api/admin_static/providers/SOURCES.md b/src/free_claude_code/api/admin_static/providers/SOURCES.md
index e8fb62f0..2baca012 100644
--- a/src/free_claude_code/api/admin_static/providers/SOURCES.md
+++ b/src/free_claude_code/api/admin_static/providers/SOURCES.md
@@ -41,6 +41,7 @@ The LLaMA.cpp icon comes from the upstream llama.cpp repository; its MIT license
| `openai.svg` | https://unpkg.com/@lobehub/[email protected]/icons/openai.svg |
| `opencode.svg` | https://unpkg.com/@lobehub/[email protected]/icons/opencode.svg |
| `openrouter.svg` | https://unpkg.com/@lobehub/[email protected]/icons/openrouter.svg |
+| `orcarouter.png` | https://www.orcarouter.ai/apple-touch-icon.png |
| `poolside-color.svg` | https://unpkg.com/@lobehub/[email protected]/icons/poolside-color.svg |
| `qwen-color.svg` | https://unpkg.com/@lobehub/[email protected]/icons/qwen-color.svg |
| `sambanova-color.svg` | https://unpkg.com/@lobehub/[email protected]/icons/sambanova-color.svg |
diff --git a/src/free_claude_code/api/admin_static/providers/orcarouter.png b/src/free_claude_code/api/admin_static/providers/orcarouter.png
new file mode 100644
index 00000000..a43be960
Binary files /dev/null and b/src/free_claude_code/api/admin_static/providers/orcarouter.png differ
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index 404e926f..febca104 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -269,6 +269,14 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, ProviderFieldOverride] = {
"lightning.ai/api/v1. Create one on lightning.ai under Model APIs."
),
},
+ "ORCAROUTER_API_KEY": {
+ "label": "OrcaRouter API Key",
+ "description": (
+ "OrcaRouter OpenAI-compatible multi-provider gateway API key for "
+ "api.orcarouter.ai/v1. Keys begin with sk-orca-; create one at "
+ "www.orcarouter.ai/console."
+ ),
+ },
"AGNES_API_KEY": {
"label": "Agnes AI API Key",
"description": (
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index d49f31ab..dd93e6fb 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -88,6 +88,8 @@ LIGHTNING_DEFAULT_BASE = "https://lightning.ai/api/v1"
EXPERIENTIAL_DEFAULT_BASE = "https://api.experientiallabs.ai/v1"
# Cheaper Inference OpenAI-compatible Chat Completions gateway.
CHEAPERINFERENCE_DEFAULT_BASE = "https://api.cheaperinference.com/v1"
+# OrcaRouter OpenAI-compatible multi-provider gateway.
+ORCAROUTER_DEFAULT_BASE = "https://api.orcarouter.ai/v1"
# Agnes AI OpenAI-compatible Chat Completions API.
AGNES_DEFAULT_BASE = "https://apihub.agnes-ai.com/v1"
# ZenMux OpenAI-compatible Chat Completions gateway.
@@ -700,6 +702,17 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=CHEAPERINFERENCE_DEFAULT_BASE,
proxy_attr="cheaperinference_proxy",
),
+ "orcarouter": ProviderDescriptor(
+ provider_id="orcarouter",
+ display_name="OrcaRouter",
+ website_url="https://www.orcarouter.ai/",
+ logo_filename="orcarouter.png",
+ credential_env="ORCAROUTER_API_KEY",
+ credential_url="https://www.orcarouter.ai/console",
+ credential_attr="orcarouter_api_key",
+ default_base_url=ORCAROUTER_DEFAULT_BASE,
+ proxy_attr="orcarouter_proxy",
+ ),
"ollama_cloud": ProviderDescriptor(
provider_id="ollama_cloud",
display_name="Ollama Cloud",
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index 6f3fa9a1..6ce7cbfe 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -239,6 +239,11 @@ class Settings(BaseModel):
default=None, validation_alias="CHEAPER_INFERENCE_API_KEY"
)
+ # ==================== OrcaRouter (OpenAI-compatible gateway) ====================
+ orcarouter_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ORCAROUTER_API_KEY"
+ )
+
# ==================== Fireworks AI Config ====================
fireworks_api_key: OptionalNonEmptyString = Field(
default=None, validation_alias="FIREWORKS_API_KEY"
@@ -545,6 +550,9 @@ class Settings(BaseModel):
cheaperinference_proxy: OptionalNonEmptyString = Field(
default=None, validation_alias="CHEAPER_INFERENCE_PROXY"
)
+ orcarouter_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ORCAROUTER_PROXY"
+ )
fireworks_proxy: OptionalNonEmptyString = Field(
default=None, validation_alias="FIREWORKS_PROXY"
)
diff --git a/src/free_claude_code/providers/credential_validation.py b/src/free_claude_code/providers/credential_validation.py
index 01b489bc..be9a4f7b 100644
--- a/src/free_claude_code/providers/credential_validation.py
+++ b/src/free_claude_code/providers/credential_validation.py
@@ -145,6 +145,7 @@ _PROBES = (
),
_Probe("nararoute", "/models", _MODELS, _AUTH_401),
_Probe("experiential", "/models", _MODELS, _AUTH_401),
+ _Probe("orcarouter", "/models", _MODELS, _AUTH_401),
# Positive evidence only: these errors can also reflect permissions, budget,
# token type, or an undocumented response contract. Never reject on failure.
# https://docs.deepinfra.com/api-reference/account/me
diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.py
index f56d6728..755450b5 100644
--- a/src/free_claude_code/providers/model_listing.py
+++ b/src/free_claude_code/providers/model_listing.py
@@ -48,6 +48,7 @@ def extract_openai_model_infos(
required_null_field: str | None = None,
required_sequence_items: tuple[tuple[str, str], ...] = (),
exclude_missing_sequence_fields: bool = False,
+ optional_sequence_items: tuple[tuple[str, str], ...] = (),
tags_field: str | None = None,
thinking_tag: str = "reasoning",
non_thinking_tag: str | None = None,
@@ -124,6 +125,22 @@ def extract_openai_model_infos(
if missing_sequence_field:
continue
+ for field_name, required_item in optional_sequence_items:
+ values = _field(item, field_name)
+ if values is None:
+ # Absent or null metadata proves nothing: keep the item listed.
+ continue
+ if not _is_sequence(values) or any(
+ not isinstance(value, str) or not value.strip() for value in values
+ ):
+ raise _malformed(
+ provider_name,
+ f"expected every {item_location} item to include "
+ f"{field_name} string array",
+ )
+ if required_item not in values:
+ included = False
+
supports_thinking: bool | None = None
intrinsic_facts: set[bool] = set()
if tags_field is not None:
diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.py
index 7ba9702f..a18df435 100644
--- a/src/free_claude_code/providers/openai_chat/profiles.py
+++ b/src/free_claude_code/providers/openai_chat/profiles.py
@@ -97,6 +97,7 @@ class OpenAIModelListing:
required_null_field: str | None = None
required_sequence_items: tuple[tuple[str, str], ...] = ()
exclude_missing_sequence_fields: bool = False
+ optional_sequence_items: tuple[tuple[str, str], ...] = ()
tags_field: str | None = None
thinking_tag: str = "reasoning"
non_thinking_tag: str | None = None
@@ -741,6 +742,18 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
max_output_tokens_path=("max_output_tokens",),
),
),
+ "orcarouter": OpenAIChatProfile(
+ _policy(
+ "ORCAROUTER",
+ ReasoningReplayMode.REASONING_CONTENT,
+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+ ),
+ NamedEffortReasoning(_LOW_MEDIUM_HIGH, enabled_value="medium"),
+ model_listing=OpenAIModelListing(
+ path="/models",
+ optional_sequence_items=(("supported_endpoint_types", "openai"),),
+ ),
+ ),
"ollama_cloud": OpenAIChatProfile(
_policy(
"OLLAMA_CLOUD",
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 1f366dec..6bb65777 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -103,6 +103,7 @@ class OpenAIChatProvider(BaseProvider):
required_null_field=listing.required_null_field,
required_sequence_items=listing.required_sequence_items,
exclude_missing_sequence_fields=listing.exclude_missing_sequence_fields,
+ optional_sequence_items=listing.optional_sequence_items,
tags_field=listing.tags_field,
thinking_tag=listing.thinking_tag,
non_thinking_tag=listing.non_thinking_tag,
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 826dabed..af321f5a 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -57,6 +57,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"lightning",
"experiential",
"cheaperinference",
+ "orcarouter",
"ollama_cloud",
"lmstudio",
"llamacpp",
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index 9457c910..c963906a 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -71,6 +71,7 @@ def _settings(**overrides):
"lightning_api_key": "",
"experiential_api_key": "",
"cheaperinference_api_key": "",
+ "orcarouter_api_key": "",
"fireworks_api_key": "",
"novita_api_key": "",
"cloudflare_api_token": "",
@@ -390,6 +391,56 @@ def test_cheaperinference_is_not_enabled_without_explicit_credential(
assert config.provider_smoke_models() == []
+def test_orcarouter_provider_configuration_uses_documented_free_model(
+ monkeypatch,
+) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_ORCAROUTER", raising=False)
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ orcarouter_api_key="orcarouter-key",
+ )
+ )
+
+ assert config.has_provider_configuration("orcarouter")
+ models = config.provider_smoke_models()
+ assert [model.provider for model in models] == ["orcarouter"]
+ assert models[0].full_model == "orcarouter/deepseek/deepseek-v4-flash-free"
+ assert models[0].source == "provider_default"
+
+
+def test_orcarouter_smoke_override_accepts_model_with_or_without_prefix(
+ monkeypatch,
+) -> None:
+ settings = _settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ orcarouter_api_key="orcarouter-key",
+ )
+ for override in (
+ "deepseek/deepseek-v4-pro-free",
+ "orcarouter/deepseek/deepseek-v4-pro-free",
+ ):
+ monkeypatch.setenv("FCC_SMOKE_MODEL_ORCAROUTER", override)
+ models = _smoke_config(settings=settings).provider_smoke_models()
+
+ assert [model.provider for model in models] == ["orcarouter"]
+ assert models[0].full_model == "orcarouter/deepseek/deepseek-v4-pro-free"
+ assert models[0].source == "FCC_SMOKE_MODEL_ORCAROUTER"
+
+
+def test_orcarouter_is_not_enabled_without_explicit_credential(monkeypatch) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_ORCAROUTER", raising=False)
+ config = _smoke_config(
+ provider_matrix=frozenset({"orcarouter"}),
+ settings=_settings(ollama_base_url="", orcarouter_api_key=""),
+ )
+
+ assert not config.has_provider_configuration("orcarouter")
+ assert config.provider_smoke_models() == []
+
+
def test_xai_provider_smoke_uses_current_grok_model(monkeypatch) -> None:
monkeypatch.delenv("FCC_SMOKE_MODEL_XAI", raising=False)
config = _smoke_config(
diff --git a/tests/providers/test_credential_validation.py b/tests/providers/test_credential_validation.py
index 8db66e8d..acdd970a 100644
--- a/tests/providers/test_credential_validation.py
+++ b/tests/providers/test_credential_validation.py
@@ -62,6 +62,7 @@ CASES = [
),
("nararoute", "https://router.bynara.id/v1/models", {"data": []}, 401),
("experiential", "https://api.experientiallabs.ai/v1/models", {"data": []}, 401),
+ ("orcarouter", "https://api.orcarouter.ai/v1/models", {"data": []}, 401),
(
"deepinfra",
"https://api.deepinfra.com/v1/me",
diff --git a/tests/providers/test_openai_model_listing_filters.py b/tests/providers/test_openai_model_listing_filters.py
index 7aa9c5e5..e3380265 100644
--- a/tests/providers/test_openai_model_listing_filters.py
+++ b/tests/providers/test_openai_model_listing_filters.py
@@ -280,3 +280,44 @@ def test_tool_capable_parser_retains_exact_input_modalities() -> None:
ProviderModelInfo("unknown-media", supports_thinking=False),
}
)
+
+
+def test_optional_sequence_items_exclude_only_confident_mismatches() -> None:
+ model_infos = extract_openai_model_infos(
+ {
+ "data": [
+ {
+ "id": "chat",
+ "supported_endpoint_types": ["openai", "anthropic"],
+ },
+ {
+ "id": "embeddings-only",
+ "supported_endpoint_types": ["embeddings"],
+ },
+ {"id": "image-only", "supported_endpoint_types": ["gemini"]},
+ {"id": "unclassified", "supported_endpoint_types": None},
+ {"id": "unreported"},
+ ]
+ },
+ provider_name="TEST",
+ optional_sequence_items=(("supported_endpoint_types", "openai"),),
+ )
+
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo("chat"),
+ ProviderModelInfo("unclassified"),
+ ProviderModelInfo("unreported"),
+ }
+ )
+
+
+def test_optional_sequence_items_still_reject_non_array_metadata() -> None:
+ with pytest.raises(
+ ModelListResponseError, match="supported_endpoint_types string array"
+ ):
+ extract_openai_model_infos(
+ {"data": [{"id": "model", "supported_endpoint_types": "openai"}]},
+ provider_name="TEST",
+ optional_sequence_items=(("supported_endpoint_types", "openai"),),
+ )
diff --git a/tests/providers/test_orcarouter.py b/tests/providers/test_orcarouter.py
new file mode 100644
index 00000000..1ee38f95
--- /dev/null
+++ b/tests/providers/test_orcarouter.py
@@ -0,0 +1,274 @@
+"""Tests for the OrcaRouter OpenAI-chat gateway profile and catalog."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import httpx2
+import pytest
+from openai import AsyncOpenAI
+
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+from free_claude_code.config.provider_catalog import ORCAROUTER_DEFAULT_BASE
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.json_types import JsonObject, JsonValue
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.openai_chat import OpenAIChatProvider
+from tests.providers.support import (
+ REASONING_DEFAULT,
+ REASONING_OFF,
+ REASONING_ON,
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+ reasoning_for,
+)
+
+_MODEL = "deepseek/deepseek-v4-flash-free"
+
+
+def orcarouter_provider() -> OpenAIChatProvider:
+ return profiled_provider(
+ "orcarouter",
+ make_provider_config(
+ api_key="test-orcarouter-key",
+ base_url=ORCAROUTER_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ ),
+ admission=immediate_admission(provider_name="orcarouter", max_attempts=1),
+ )
+
+
+def _request(**overrides: JsonValue) -> MessagesRequest:
+ payload: JsonObject = {
+ "model": _MODEL,
+ "messages": [{"role": "user", "content": "Inspect the file."}],
+ "tools": [
+ {
+ "name": "read_file",
+ "description": "Read a file",
+ "input_schema": {
+ "type": "object",
+ "properties": {"path": {"type": "string"}},
+ "required": ["path"],
+ },
+ }
+ ],
+ }
+ payload.update(overrides)
+ return MessagesRequest.model_validate(payload)
+
+
+def test_constructs_standard_openai_chat_provider(
+ orcarouter_provider: OpenAIChatProvider,
+) -> None:
+ assert isinstance(orcarouter_provider, OpenAIChatProvider)
+ assert orcarouter_provider._provider_name == "ORCAROUTER"
+ assert orcarouter_provider._api_key == "test-orcarouter-key"
+ assert orcarouter_provider._base_url == ORCAROUTER_DEFAULT_BASE
+
+
+ ("reasoning", "expected"),
+ [
+ (REASONING_DEFAULT, None),
+ (REASONING_OFF, None),
+ (REASONING_ON, "medium"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.MINIMAL), "low"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.LOW), "low"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.MEDIUM), "medium"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.HIGH), "high"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.XHIGH), "high"),
+ (ReasoningPolicy.on(effort=ReasoningEffort.MAX), "high"),
+ ],
+)
+def test_encodes_only_documented_reasoning_efforts(
+ orcarouter_provider: OpenAIChatProvider,
+ reasoning: ReasoningPolicy,
+ expected: str | None,
+) -> None:
+ body = orcarouter_provider._chat._build_request_body(
+ _request(),
+ reasoning=reasoning,
+ )
+
+ assert body.get("reasoning_effort") == expected
+ assert body["max_tokens"] == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+ assert body["model"] == _MODEL
+ assert body["tools"][0]["function"]["name"] == "read_file"
+ assert "thinking" not in body
+ assert "extra_body" not in body
+
+
+def test_replays_reasoning_content_with_tool_history(
+ orcarouter_provider: OpenAIChatProvider,
+) -> None:
+ request = _request(
+ messages=[
+ {"role": "user", "content": "Inspect the file."},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "Read it first."},
+ {"type": "text", "text": "I will inspect it."},
+ {
+ "type": "tool_use",
+ "id": "toolu_1",
+ "name": "read_file",
+ "input": {"path": "example.py"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "toolu_1",
+ "content": "print('hello')",
+ }
+ ],
+ },
+ ]
+ )
+
+ body = orcarouter_provider._chat._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assert body["messages"][1] == {
+ "role": "assistant",
+ "content": "I will inspect it.",
+ "reasoning_content": "Read it first.",
+ "tool_calls": [
+ {
+ "id": "toolu_1",
+ "type": "function",
+ "function": {
+ "name": "read_file",
+ "arguments": '{"path": "example.py"}',
+ },
+ }
+ ],
+ }
+ assert body["messages"][2] == {
+ "role": "tool",
+ "tool_call_id": "toolu_1",
+ "content": "print('hello')",
+ }
+ assert (
+ orcarouter_provider._profile.reasoning_delta(
+ SimpleNamespace(reasoning_content="next thought")
+ )
+ == "next thought"
+ )
+
+
+async def test_model_catalog_extracts_bare_model_ids(
+ orcarouter_provider: OpenAIChatProvider,
+) -> None:
+ orcarouter_provider._client.get = AsyncMock(
+ return_value={"data": [{"id": _MODEL}, {"id": "orcarouter/free"}]}
+ )
+
+ model_infos = await orcarouter_provider.list_model_infos()
+
+ assert model_infos == frozenset(
+ {ProviderModelInfo(_MODEL), ProviderModelInfo("orcarouter/free")}
+ )
+ orcarouter_provider._client.get.assert_awaited_once_with(
+ "/models",
+ cast_to=object,
+ )
+
+
+ ("payload", "message"),
+ [
+ ({"models": []}, "expected top-level data array"),
+ ({"data": [{}]}, "include id"),
+ ({"data": []}, "did not include any model ids"),
+ ],
+)
+async def test_rejects_malformed_or_empty_catalog_atomically(
+ orcarouter_provider: OpenAIChatProvider,
+ payload: object,
+ message: str,
+) -> None:
+ orcarouter_provider._client.get = AsyncMock(return_value=payload)
+
+ with pytest.raises(ModelListResponseError, match=message):
+ await orcarouter_provider.list_model_infos()
+
+
+async def test_model_catalog_uses_documented_url_and_bearer_auth(
+ orcarouter_provider: OpenAIChatProvider,
+) -> None:
+ requests: list[httpx2.Request] = []
+
+ def handler(request: httpx2.Request) -> httpx2.Response:
+ requests.append(request)
+ return httpx2.Response(200, json={"data": [{"id": _MODEL}]})
+
+ await orcarouter_provider._client.close()
+ orcarouter_provider._client = AsyncOpenAI(
+ api_key="wire-orcarouter-key",
+ base_url=ORCAROUTER_DEFAULT_BASE,
+ max_retries=0,
+ http_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)),
+ )
+ try:
+ model_infos = await orcarouter_provider.list_model_infos()
+ finally:
+ await orcarouter_provider.cleanup()
+
+ assert model_infos == frozenset({ProviderModelInfo(_MODEL)})
+ assert len(requests) == 1
+ assert str(requests[0].url) == "https://api.orcarouter.ai/v1/models"
+ assert requests[0].headers["authorization"] == "Bearer wire-orcarouter-key"
+
+
+async def test_lists_only_chat_completions_capable_models(
+ orcarouter_provider: OpenAIChatProvider,
+) -> None:
+ orcarouter_provider._client.get = AsyncMock(
+ return_value={
+ "data": [
+ {
+ "id": "chat-model",
+ "supported_endpoint_types": ["openai", "anthropic"],
+ },
+ {"id": _MODEL, "supported_endpoint_types": None},
+ {
+ "id": "google/gemini-embedding-001",
+ "supported_endpoint_types": ["embeddings"],
+ },
+ {
+ "id": "google/gemini-3-pro-image-preview",
+ "supported_endpoint_types": ["gemini"],
+ },
+ {
+ "id": "openai/gpt-4o-mini",
+ "supported_endpoint_types": ["openai"],
+ },
+ ]
+ }
+ )
+
+ model_infos = await orcarouter_provider.list_model_infos()
+
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo("chat-model"),
+ ProviderModelInfo(_MODEL),
+ ProviderModelInfo("openai/gpt-4o-mini"),
+ }
+ )
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 78e525ae..02ecce18 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -27,6 +27,7 @@ from free_claude_code.config.provider_catalog import (
MINIMAX_DEFAULT_BASE,
NEBIUS_DEFAULT_BASE,
OLLAMA_CLOUD_DEFAULT_BASE,
+ ORCAROUTER_DEFAULT_BASE,
POOLSIDE_DEFAULT_BASE,
PROVIDER_CATALOG,
QWENCLOUD_CODING_DEFAULT_BASE,
@@ -116,6 +117,7 @@ def _make_settings(**overrides):
mock.lightning_api_key = "test_lightning_key"
mock.experiential_api_key = "test_experiential_key"
mock.cheaperinference_api_key = "test_cheaperinference_key"
+ mock.orcarouter_api_key = "test_orcarouter_key"
mock.nvidia_nim_proxy = None
mock.open_router_proxy = None
mock.lmstudio_proxy = None
@@ -165,6 +167,7 @@ def _make_settings(**overrides):
mock.lightning_proxy = None
mock.experiential_proxy = None
mock.cheaperinference_proxy = None
+ mock.orcarouter_proxy = None
mock.kilo_api_key = "test_kilo_key"
mock.kilo_proxy = None
mock.openai_proxy = None
@@ -351,6 +354,32 @@ async def test_cheaperinference_provider_config_uses_key_base_and_proxy() -> Non
assert isinstance(provider, OpenAIChatProvider)
+async def test_orcarouter_provider_config_uses_key_base_and_proxy() -> None:
+ descriptor = PROVIDER_CATALOG["orcarouter"]
+ settings = _make_settings(
+ orcarouter_api_key="orcarouter-token",
+ orcarouter_base_url="https://unused.example/v1",
+ orcarouter_proxy="http://proxy.test:8080",
+ )
+
+ config = build_provider_config(descriptor, settings)
+ with patch("free_claude_code.providers.openai_chat.client.AsyncOpenAI"):
+ provider = await create_provider("orcarouter", settings)
+
+ assert descriptor.display_name == "OrcaRouter"
+ assert descriptor.credential_env == "ORCAROUTER_API_KEY"
+ assert descriptor.credential_attr == "orcarouter_api_key"
+ assert descriptor.credential_url == "https://www.orcarouter.ai/console"
+ assert descriptor.default_base_url == ORCAROUTER_DEFAULT_BASE
+ assert descriptor.base_url_attr is None
+ assert descriptor.proxy_attr == "orcarouter_proxy"
+ assert config.api_key == "orcarouter-token"
+ assert config.base_url == ORCAROUTER_DEFAULT_BASE
+ assert config.proxy == "http://proxy.test:8080"
+ assert isinstance(provider, OpenAIChatProvider)
+
+
@pytest.mark.asyncio
async def test_xai_provider_config_uses_key_base_and_proxy() -> None:
descriptor = PROVIDER_CATALOG["xai"]
@@ -991,6 +1020,7 @@ async def test_create_provider_instantiates_each_builtin():
"lightning": OpenAIChatProvider,
"experiential": OpenAIChatProvider,
"cheaperinference": OpenAIChatProvider,
+ "orcarouter": OpenAIChatProvider,
"opencode_go": OpenCodeProvider,
"vercel": OpenAIChatProvider,
"bedrock": OpenAIChatProvider,