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

feat(opencode): integrate OpenCode Zen provider and API key support (#426)

Rizki Kotet32e2e4d7557c
diff --git a/.env.example b/.env.example
index 7f710722..88dca390 100644
--- a/.env.example
+++ b/.env.example
@@ -18,6 +18,10 @@ KIMI_API_KEY=""
WAFER_API_KEY=""
+# OpenCode Zen Config (OpenAI-compatible Chat Completions at opencode.ai/zen/v1)
+OPENCODE_API_KEY=""
+
+
# LM Studio Config (local provider, no API key required)
LM_STUDIO_BASE_URL="http://localhost:1234/v1"
@@ -32,7 +36,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" | "open_router" | "deepseek" | "lmstudio" | "llamacpp" | "ollama" | "kimi" | "wafer"
+# Valid providers: "nvidia_nim" | "open_router" | "deepseek" | "lmstudio" | "llamacpp" | "ollama" | "kimi" | "wafer" | "opencode"
MODEL_OPUS=
MODEL_SONNET=
MODEL_HAIKU=
@@ -49,6 +53,7 @@ FCC_SMOKE_MODEL_LLAMACPP=
FCC_SMOKE_MODEL_OLLAMA=
FCC_SMOKE_MODEL_KIMI=
FCC_SMOKE_MODEL_WAFER=
+FCC_SMOKE_MODEL_OPENCODE=
FCC_SMOKE_NIM_MODELS=
FCC_SMOKE_NIM_EXTRA_MODELS=
FCC_SMOKE_OPENROUTER_FREE_MODELS=
@@ -72,6 +77,7 @@ LMSTUDIO_PROXY=""
LLAMACPP_PROXY=""
KIMI_PROXY=""
WAFER_PROXY=""
+OPENCODE_PROXY=""
PROVIDER_RATE_LIMIT=1
PROVIDER_RATE_WINDOW=3
diff --git a/README.md b/README.md
index ee0cc022..a5826285 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code to NVIDI
## What You Get
- Drop-in proxy for Claude Code's Anthropic API calls.
-- Eight provider backends: NVIDIA NIM, Kimi, Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama.
+- Nine provider backends: NVIDIA NIM, Kimi, Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, Ollama, and OpenCode Zen.
- Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers.
- Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (Claude Code must opt in to Gateway model discovery; see [Model Picker](#model-picker)).
- Streaming, tool use, reasoning/thinking block handling, and local request optimizations.
@@ -208,11 +208,30 @@ In the Admin UI, keep or update `OLLAMA_BASE_URL`, then set `MODEL` to the same
`OLLAMA_BASE_URL` is the Ollama server root; do not append `/v1`. Example model slugs include `ollama/llama3.1` and `ollama/llama3.1:8b`.
-### 9. Mix Providers By Model Tier
+### 9. [OpenCode Zen](https://opencode.ai/)
+
+Get an API key at [opencode.ai/auth](https://opencode.ai/auth).
+
+In the Admin UI, paste it into `OPENCODE_API_KEY`, then set `MODEL` to an OpenCode Zen model slug such as `opencode/gpt-5.3-codex`.
+
+OpenCode Zen is a curated model gateway that provides access to models from Anthropic, OpenAI, Google, DeepSeek, and more through a single API key and OpenAI-compatible endpoint at `https://opencode.ai/zen/v1`.
+
+Popular examples:
+
+- `opencode/gpt-5.3-codex`
+- `opencode/claude-sonnet-4`
+- `opencode/deepseek-v4-flash-free` (free)
+- `opencode/gemini-3-flash`
+- `opencode/big-pickle` (free)
+- `opencode/glm-5.1`
+
+Browse available models at [opencode.ai](https://opencode.ai).
+
+### 10. Mix Providers By Model Tier
Each model tier can use a different provider by setting `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` in the Admin UI. Leave a tier blank to inherit `MODEL`.
-For example, you can route Opus to `nvidia_nim/moonshotai/kimi-k2.5`, Sonnet to `open_router/deepseek/deepseek-r1-0528:free`, Haiku to `lmstudio/unsloth/GLM-4.7-Flash-GGUF`, and keep the fallback `MODEL` on `wafer/DeepSeek-V4-Pro`.
+For example, you can route Opus to `nvidia_nim/moonshotai/kimi-k2.5`, Sonnet to `open_router/deepseek/deepseek-r1-0528:free`, Haiku to `lmstudio/unsloth/GLM-4.7-Flash-GGUF`, and keep the fallback `MODEL` on `opencode/gpt-5.3-codex`.
## Connect Claude Code
@@ -364,6 +383,7 @@ NVIDIA_NIM_API_KEY=""
OPENROUTER_API_KEY=""
DEEPSEEK_API_KEY=""
WAFER_API_KEY=""
+OPENCODE_API_KEY=""
LM_STUDIO_BASE_URL="http://localhost:1234/v1"
LLAMACPP_BASE_URL="http://localhost:8080/v1"
OLLAMA_BASE_URL="http://localhost:11434"
@@ -377,6 +397,7 @@ OPENROUTER_PROXY=""
LMSTUDIO_PROXY=""
LLAMACPP_PROXY=""
WAFER_PROXY=""
+OPENCODE_PROXY=""
```
### 4. Rate Limits And Timeouts
@@ -430,7 +451,7 @@ Important pieces:
- FastAPI exposes Anthropic-compatible routes such as `/v1/messages`, `/v1/messages/count_tokens`, and `/v1/models`.
- Model routing resolves the Claude model name to `MODEL_OPUS`, `MODEL_SONNET`, `MODEL_HAIKU`, or `MODEL`.
-- NIM uses OpenAI chat streaming translated into Anthropic SSE.
+- NIM, OpenCode Zen use OpenAI chat streaming translated into Anthropic SSE.
- Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama use Anthropic Messages style transports.
- The proxy normalizes thinking blocks, tool calls, token usage metadata, and provider errors into the shape Claude Code expects.
- Request optimizations answer trivial Claude Code probes locally to save latency and quota.
diff --git a/api/admin_config.py b/api/admin_config.py
index 9a37e7fe..c13d22d8 100644
--- a/api/admin_config.py
+++ b/api/admin_config.py
@@ -158,6 +158,15 @@ FIELDS: tuple[ConfigFieldSpec, ...] = (
settings_attr="wafer_api_key",
secret=True,
),
+ ConfigFieldSpec(
+ "OPENCODE_API_KEY",
+ "OpenCode Zen API Key",
+ "providers",
+ "secret",
+ settings_attr="opencode_api_key",
+ secret=True,
+ description="OpenCode Zen curated model gateway at opencode.ai.",
+ ),
ConfigFieldSpec(
"LM_STUDIO_BASE_URL",
"LM Studio Base URL",
@@ -233,6 +242,15 @@ FIELDS: tuple[ConfigFieldSpec, ...] = (
secret=True,
advanced=True,
),
+ ConfigFieldSpec(
+ "OPENCODE_PROXY",
+ "OpenCode Zen Proxy",
+ "providers",
+ "secret",
+ settings_attr="opencode_proxy",
+ secret=True,
+ advanced=True,
+ ),
ConfigFieldSpec(
"MODEL",
"Default Model",
@@ -693,6 +711,12 @@ FIELDS: tuple[ConfigFieldSpec, ...] = (
"smoke",
advanced=True,
),
+ ConfigFieldSpec(
+ "FCC_SMOKE_MODEL_OPENCODE",
+ "Smoke OpenCode Zen Model",
+ "smoke",
+ advanced=True,
+ ),
ConfigFieldSpec(
"FCC_SMOKE_NIM_MODELS",
"Smoke NIM Models",
diff --git a/api/admin_static/admin.js b/api/admin_static/admin.js
index 0f3d69a1..6603db40 100644
--- a/api/admin_static/admin.js
+++ b/api/admin_static/admin.js
@@ -32,6 +32,7 @@ function providerName(providerId) {
ollama: "Ollama",
kimi: "Kimi",
wafer: "Wafer",
+ opencode: "OpenCode Zen",
};
if (names[providerId]) return names[providerId];
return providerId
diff --git a/api/services.py b/api/services.py
index 9611e516..711bc277 100644
--- a/api/services.py
+++ b/api/services.py
@@ -34,7 +34,7 @@ TokenCounter = Callable[[list[Any], str | list[Any] | None, list[Any] | None], i
ProviderGetter = Callable[[str], BaseProvider]
# Providers that use ``/chat/completions`` + Anthropic-to-OpenAI conversion (not native Messages).
-_OPENAI_CHAT_UPSTREAM_IDS = frozenset({"nvidia_nim"})
+_OPENAI_CHAT_UPSTREAM_IDS = frozenset({"nvidia_nim", "opencode"})
def anthropic_sse_streaming_response(
diff --git a/config/provider_catalog.py b/config/provider_catalog.py
index 62eff7ee..f10194d9 100644
--- a/config/provider_catalog.py
+++ b/config/provider_catalog.py
@@ -23,6 +23,7 @@ OPENROUTER_DEFAULT_BASE = "https://openrouter.ai/api/v1"
LMSTUDIO_DEFAULT_BASE = "http://localhost:1234/v1"
LLAMACPP_DEFAULT_BASE = "http://localhost:8080/v1"
OLLAMA_DEFAULT_BASE = "http://localhost:11434"
+OPENCODE_DEFAULT_BASE = "https://opencode.ai/zen/v1"
@dataclass(frozen=True, slots=True)
@@ -124,6 +125,16 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
proxy_attr="wafer_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),
),
+ "opencode": ProviderDescriptor(
+ provider_id="opencode",
+ transport_type="openai_chat",
+ credential_env="OPENCODE_API_KEY",
+ credential_url="https://opencode.ai/auth",
+ credential_attr="opencode_api_key",
+ default_base_url=OPENCODE_DEFAULT_BASE,
+ proxy_attr="opencode_proxy",
+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
+ ),
}
# Order matches docs / historical error text; must match PROVIDER_CATALOG keys.
diff --git a/config/settings.py b/config/settings.py
index d08804f0..f2016008 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -118,6 +118,9 @@ class Settings(BaseSettings):
# ==================== Wafer Config ====================
wafer_api_key: str = Field(default="", validation_alias="WAFER_API_KEY")
+ # ==================== OpenCode Zen Config ====================
+ opencode_api_key: str = Field(default="", validation_alias="OPENCODE_API_KEY")
+
# ==================== Messaging Platform Selection ====================
# Valid: "telegram" | "discord" | "none"
messaging_platform: str = Field(
@@ -169,6 +172,7 @@ class Settings(BaseSettings):
llamacpp_proxy: str = Field(default="", validation_alias="LLAMACPP_PROXY")
kimi_proxy: str = Field(default="", validation_alias="KIMI_PROXY")
wafer_proxy: str = Field(default="", validation_alias="WAFER_PROXY")
+ opencode_proxy: str = Field(default="", validation_alias="OPENCODE_PROXY")
# ==================== Provider Rate Limiting ====================
provider_rate_limit: int = Field(default=40, validation_alias="PROVIDER_RATE_LIMIT")
diff --git a/providers/defaults.py b/providers/defaults.py
index 2d4d6507..d411f1e2 100644
--- a/providers/defaults.py
+++ b/providers/defaults.py
@@ -8,6 +8,7 @@ from config.provider_catalog import (
LMSTUDIO_DEFAULT_BASE,
NVIDIA_NIM_DEFAULT_BASE,
OLLAMA_DEFAULT_BASE,
+ OPENCODE_DEFAULT_BASE,
OPENROUTER_DEFAULT_BASE,
WAFER_DEFAULT_BASE,
)
@@ -20,6 +21,7 @@ __all__ = (
"LMSTUDIO_DEFAULT_BASE",
"NVIDIA_NIM_DEFAULT_BASE",
"OLLAMA_DEFAULT_BASE",
+ "OPENCODE_DEFAULT_BASE",
"OPENROUTER_DEFAULT_BASE",
"WAFER_DEFAULT_BASE",
)
diff --git a/providers/opencode/__init__.py b/providers/opencode/__init__.py
new file mode 100644
index 00000000..19e3c479
--- /dev/null
+++ b/providers/opencode/__init__.py
@@ -0,0 +1,10 @@
+"""OpenCode Zen provider exports."""
+
+from providers.defaults import OPENCODE_DEFAULT_BASE
+
+from .client import OpenCodeProvider
+
+__all__ = [
+ "OPENCODE_DEFAULT_BASE",
+ "OpenCodeProvider",
+]
diff --git a/providers/opencode/client.py b/providers/opencode/client.py
new file mode 100644
index 00000000..bf15a0b3
--- /dev/null
+++ b/providers/opencode/client.py
@@ -0,0 +1,31 @@
+"""OpenCode Zen provider implementation (OpenAI-compatible Chat Completions)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from providers.base import ProviderConfig
+from providers.defaults import OPENCODE_DEFAULT_BASE
+from providers.openai_compat import OpenAIChatTransport
+
+from .request import build_request_body
+
+
+class OpenCodeProvider(OpenAIChatTransport):
+ """OpenCode Zen provider using ``https://opencode.ai/zen/v1/chat/completions``."""
+
+ def __init__(self, config: ProviderConfig):
+ super().__init__(
+ config,
+ provider_name="OPENCODE",
+ base_url=config.base_url or OPENCODE_DEFAULT_BASE,
+ api_key=config.api_key,
+ )
+
+ def _build_request_body(
+ self, request: Any, thinking_enabled: bool | None = None
+ ) -> dict:
+ return build_request_body(
+ request,
+ thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+ )
diff --git a/providers/opencode/request.py b/providers/opencode/request.py
new file mode 100644
index 00000000..243b945c
--- /dev/null
+++ b/providers/opencode/request.py
@@ -0,0 +1,35 @@
+"""Request builder for OpenCode Zen provider."""
+
+from typing import Any
+
+from loguru import logger
+
+from core.anthropic import ReasoningReplayMode, build_base_request_body
+from core.anthropic.conversion import OpenAIConversionError
+from providers.exceptions import InvalidRequestError
+
+
+def build_request_body(request_data: Any, *, thinking_enabled: bool) -> dict:
+ """Build OpenAI-format request body from Anthropic request for OpenCode Zen."""
+ logger.debug(
+ "OPENCODE_REQUEST: conversion start model={} msgs={}",
+ getattr(request_data, "model", "?"),
+ len(getattr(request_data, "messages", [])),
+ )
+ try:
+ body = build_base_request_body(
+ request_data,
+ reasoning_replay=ReasoningReplayMode.REASONING_CONTENT
+ if thinking_enabled
+ else ReasoningReplayMode.DISABLED,
+ )
+ except OpenAIConversionError as exc:
+ raise InvalidRequestError(str(exc)) from exc
+
+ logger.debug(
+ "OPENCODE_REQUEST: conversion done model={} msgs={} tools={}",
+ body.get("model"),
+ len(body.get("messages", [])),
+ len(body.get("tools", [])),
+ )
+ return body
diff --git a/providers/registry.py b/providers/registry.py
index 7375048c..dab8260a 100644
--- a/providers/registry.py
+++ b/providers/registry.py
@@ -80,6 +80,12 @@ def _create_wafer(config: ProviderConfig, _settings: Settings) -> BaseProvider:
return WaferProvider(config)
+def _create_opencode(config: ProviderConfig, _settings: Settings) -> BaseProvider:
+ from providers.opencode import OpenCodeProvider
+
+ return OpenCodeProvider(config)
+
+
PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"nvidia_nim": _create_nvidia_nim,
"open_router": _create_open_router,
@@ -89,6 +95,7 @@ PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"ollama": _create_ollama,
"kimi": _create_kimi,
"wafer": _create_wafer,
+ "opencode": _create_opencode,
}
if set(PROVIDER_DESCRIPTORS) != set(SUPPORTED_PROVIDER_IDS) or set(
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index f23f28c0..b12d5e87 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -49,6 +49,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"llamacpp": "llamacpp/local-model",
"ollama": "ollama/llama3.1",
"wafer": "wafer/DeepSeek-V4-Pro",
+ "opencode": "opencode/gpt-5.3-codex",
}
NVIDIA_NIM_CLI_DEFAULT_MODELS: tuple[str, ...] = (
@@ -231,6 +232,8 @@ class SmokeConfig:
return bool(self.settings.ollama_base_url.strip())
if provider == "wafer":
return bool(self.settings.wafer_api_key.strip())
+ if provider == "opencode":
+ return bool(self.settings.opencode_api_key.strip())
return False
diff --git a/tests/api/test_dependencies.py b/tests/api/test_dependencies.py
index b2e068d2..1a64d4be 100644
--- a/tests/api/test_dependencies.py
+++ b/tests/api/test_dependencies.py
@@ -37,12 +37,14 @@ def _make_mock_settings(**overrides):
mock.open_router_api_key = "test_openrouter_key"
mock.deepseek_api_key = "test_deepseek_key"
mock.wafer_api_key = "test_wafer_key"
+ mock.opencode_api_key = "test_opencode_key"
mock.lm_studio_base_url = "http://localhost:1234/v1"
mock.ollama_base_url = "http://localhost:11434"
mock.lmstudio_proxy = ""
mock.llamacpp_proxy = ""
mock.kimi_proxy = ""
mock.wafer_proxy = ""
+ mock.opencode_proxy = ""
mock.nim = NimSettings()
mock.http_read_timeout = 300.0
mock.http_write_timeout = 10.0
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index a514de53..51cf944b 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -11,6 +11,7 @@ from providers.lmstudio import LMStudioProvider
from providers.nvidia_nim import NvidiaNimProvider
from providers.ollama import OllamaProvider
from providers.open_router import OpenRouterProvider
+from providers.opencode import OpenCodeProvider
from providers.wafer import WaferProvider
from smoke.features import FEATURE_INVENTORY, README_FEATURES, feature_ids
@@ -75,6 +76,7 @@ def test_provider_and_platform_registries_include_advertised_builtins() -> None:
"llamacpp": LlamaCppProvider,
"ollama": OllamaProvider,
"wafer": WaferProvider,
+ "opencode": OpenCodeProvider,
}
for provider_class in provider_classes.values():
assert issubclass(provider_class, BaseProvider)
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index 3b368aa3..d82ee56a 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -27,6 +27,7 @@ def _settings(**overrides):
"open_router_api_key": "",
"deepseek_api_key": "",
"wafer_api_key": "",
+ "opencode_api_key": "",
"lm_studio_base_url": "",
"llamacpp_base_url": "",
"ollama_base_url": "http://localhost:11434",
diff --git a/tests/providers/test_model_validation.py b/tests/providers/test_model_validation.py
index d54b9816..ae64100b 100644
--- a/tests/providers/test_model_validation.py
+++ b/tests/providers/test_model_validation.py
@@ -33,6 +33,7 @@ def _settings(
open_router_api_key: str = "",
deepseek_api_key: str = "",
wafer_api_key: str = "",
+ opencode_api_key: str = "",
) -> Settings:
return Settings.model_construct(
model=model,
@@ -43,6 +44,7 @@ def _settings(
open_router_api_key=open_router_api_key,
deepseek_api_key=deepseek_api_key,
wafer_api_key=wafer_api_key,
+ opencode_api_key=opencode_api_key,
log_api_error_tracebacks=False,
)
diff --git a/tests/providers/test_registry.py b/tests/providers/test_registry.py
index 0b02d59b..e4da84bd 100644
--- a/tests/providers/test_registry.py
+++ b/tests/providers/test_registry.py
@@ -13,6 +13,7 @@ from providers.lmstudio import LMStudioProvider
from providers.nvidia_nim import NvidiaNimProvider
from providers.ollama import OllamaProvider
from providers.open_router import OpenRouterProvider
+from providers.opencode import OpenCodeProvider
from providers.registry import (
PROVIDER_DESCRIPTORS,
ProviderRegistry,
@@ -29,6 +30,7 @@ def _make_settings(**overrides):
mock.open_router_api_key = "test_openrouter_key"
mock.deepseek_api_key = "test_deepseek_key"
mock.wafer_api_key = "test_wafer_key"
+ mock.opencode_api_key = "test_opencode_key"
mock.lm_studio_base_url = "http://localhost:1234/v1"
mock.llamacpp_base_url = "http://localhost:8080/v1"
mock.ollama_base_url = "http://localhost:11434"
@@ -38,6 +40,7 @@ def _make_settings(**overrides):
mock.llamacpp_proxy = ""
mock.kimi_proxy = ""
mock.wafer_proxy = ""
+ mock.opencode_proxy = ""
mock.provider_rate_limit = 40
mock.provider_rate_window = 60
mock.provider_max_concurrency = 5
@@ -99,6 +102,7 @@ def test_create_provider_instantiates_each_builtin():
"llamacpp": LlamaCppProvider,
"ollama": OllamaProvider,
"wafer": WaferProvider,
+ "opencode": OpenCodeProvider,
}
with (