Skip to content

🙌 OpenHands: AI-Driven Development

feat: OHE multi-model LLM discovery + BYOK gating (proxy discovery, catalogue union, UX) (#14773)

Alonaa6bce82148c6
diff --git a/enterprise/server/verified_models/litellm_proxy_model_router.py b/enterprise/server/verified_models/litellm_proxy_model_router.py
new file mode 100644
index 0000000000..a037721d1f
--- /dev/null
+++ b/enterprise/server/verified_models/litellm_proxy_model_router.py
@@ -0,0 +1,291 @@
+"""LiteLLM-proxy-backed LLM model discovery for self-hosted enterprise (OHE).
+
+Self-hosted enterprise installs bundle a LiteLLM proxy, and the set of models
+that actually works for a customer is exactly the set configured on that
+proxy. This service discovers models from the proxy's ``GET /model/info``
+endpoint instead of unioning the static litellm catalogue and the SaaS
+``verified_models`` database table, so the model dropdown only shows models
+that genuinely exist on the customer's proxy.
+
+Activate via the environment variable::
+
+ OH_LLM_MODEL_KIND=server.verified_models.litellm_proxy_model_router.LiteLLMProxyModelServiceInjector
+"""
+
+import asyncio
+import logging
+import time
+from typing import Any, AsyncGenerator, ClassVar
+
+import httpx
+from fastapi import Request
+from server.constants import (
+ LITE_LLM_API_KEY,
+ LITE_LLM_API_URL,
+ get_default_litellm_model,
+)
+
+from openhands.app_server.config_api.default_llm_model_service import (
+ DefaultLLMModelService,
+)
+from openhands.app_server.config_api.llm_model_service import (
+ LLMModelService,
+ LLMModelServiceInjector,
+)
+from openhands.app_server.services.injector import InjectorState
+from openhands.app_server.utils.http_session import httpx_verify_option
+from openhands.app_server.utils.llm import ModelsResponse, get_supported_llm_models
+
+_logger = logging.getLogger(__name__)
+
+# Timeout (seconds) for the proxy /model/info request.
+MODEL_INFO_TIMEOUT = 5.0
+# How long (seconds) a successful discovery result is reused before refetching.
+CACHE_TTL_SECONDS = 60.0
+
+# The proxy-transport prefix used by LITELLM_DEFAULT_MODEL.
+_LITELLM_PROXY_PREFIX = 'litellm_proxy/'
+# The public/stored prefix used by the app. The SDK translates
+# ``openhands/`` -> ``litellm_proxy/`` at the transport boundary.
+_OPENHANDS_PREFIX = 'openhands/'
+
+
+def _derive_default_model() -> str:
+ """Translate the env-derived default model to the public prefix.
+
+ ``LITELLM_DEFAULT_MODEL`` holds the default as ``litellm_proxy/<name>``;
+ the app stores and displays models as ``openhands/<name>``. An already-
+ ``openhands/``-prefixed default is kept as-is; a bare name is prefixed.
+ """
+ default = get_default_litellm_model()
+ if default.startswith(_LITELLM_PROXY_PREFIX):
+ return _OPENHANDS_PREFIX + default[len(_LITELLM_PROXY_PREFIX) :]
+ if default.startswith(_OPENHANDS_PREFIX):
+ return default
+ return _OPENHANDS_PREFIX + default
+
+
+class LiteLLMProxyModelService(DefaultLLMModelService):
+ """Model discovery backed by the bundled LiteLLM proxy.
+
+ Inherits filtering, pagination, and provider logic from
+ ``DefaultLLMModelService`` — only the model list source is different.
+
+ Results are cached at class level (the injector creates a new service per
+ request) with a short TTL. On fetch failure the last-good result is
+ served regardless of age; if there has never been a successful fetch an
+ empty model list is returned. Discovery never raises out of the request
+ path just because the proxy is briefly unreachable.
+ """
+
+ # Shared across instances; one service instance is created per request.
+ _shared_response: ClassVar[ModelsResponse | None] = None
+ _shared_fetched_at: ClassVar[float] = 0.0
+ _fetch_lock: ClassVar[asyncio.Lock] = asyncio.Lock()
+
+ @classmethod
+ def _reset_cache(cls) -> None:
+ """Clear the shared cache (intended for tests)."""
+ cls._shared_response = None
+ cls._shared_fetched_at = 0.0
+
+ @staticmethod
+ def _now() -> float:
+ """Monotonic clock; isolated for tests."""
+ return time.monotonic()
+
+ async def _fetch_proxy_model_names(
+ self,
+ ) -> tuple[list[str], list[str], dict[str, str]]:
+ """Fetch ``(visible, hidden, canonicals)`` model names from the proxy.
+
+ Entries flagged ``model_info.openhands_hidden`` (legacy alias routes
+ the proxy still serves after a rename) are collected separately: they
+ must not be offered as dropdown options, but a saved setting that
+ references one is still valid. A hidden entry may carry
+ ``model_info.openhands_canonical`` naming the visible route it
+ aliases; ``canonicals`` maps hidden name -> canonical name, dropping
+ mappings whose target is not among the visible names. A duplicated
+ ``model_name`` is an intentional load-balanced deployment — it is
+ reported once, and is hidden only when *every* entry carrying that
+ name is hidden. Proxy order is preserved. ``litellm_params`` are
+ never propagated.
+ """
+ url = LITE_LLM_API_URL.rstrip('/') + '/model/info'
+ headers: dict[str, str] = {}
+ if LITE_LLM_API_KEY:
+ headers['Authorization'] = f'Bearer {LITE_LLM_API_KEY}'
+ async with httpx.AsyncClient(
+ verify=httpx_verify_option(), timeout=MODEL_INFO_TIMEOUT
+ ) as client:
+ response = await client.get(url, headers=headers)
+ response.raise_for_status()
+ payload = response.json()
+
+ order: list[str] = []
+ hidden_by_name: dict[str, bool] = {}
+ canonical_by_name: dict[str, str] = {}
+ for entry in payload.get('data') or []:
+ if not isinstance(entry, dict):
+ continue
+ name = entry.get('model_name')
+ if not name or not isinstance(name, str):
+ continue
+ model_info: Any = entry.get('model_info') or {}
+ hidden = isinstance(model_info, dict) and bool(
+ model_info.get('openhands_hidden')
+ )
+ if hidden and name not in canonical_by_name:
+ canonical = model_info.get('openhands_canonical')
+ if canonical and isinstance(canonical, str):
+ canonical_by_name[name] = canonical
+ if name not in hidden_by_name:
+ order.append(name)
+ hidden_by_name[name] = hidden
+ elif not hidden:
+ # Any visible deployment makes the name visible.
+ hidden_by_name[name] = False
+ visible = [name for name in order if not hidden_by_name[name]]
+ hidden_names = [name for name in order if hidden_by_name[name]]
+ visible_set = set(visible)
+ canonicals = {
+ name: canonical_by_name[name]
+ for name in hidden_names
+ if canonical_by_name.get(name) in visible_set
+ }
+ return visible, hidden_names, canonicals
+
+ @staticmethod
+ def _build_response(
+ model_names: list[str],
+ hidden_model_names: list[str] | None = None,
+ hidden_model_canonicals: dict[str, str] | None = None,
+ ) -> ModelsResponse:
+ return ModelsResponse(
+ models=[_OPENHANDS_PREFIX + name for name in model_names],
+ verified_models=list(model_names),
+ verified_providers=['openhands'],
+ default_model=_derive_default_model(),
+ hidden_models=[
+ _OPENHANDS_PREFIX + name for name in hidden_model_names or []
+ ],
+ hidden_model_canonicals={
+ _OPENHANDS_PREFIX + alias: _OPENHANDS_PREFIX + canonical
+ for alias, canonical in (hidden_model_canonicals or {}).items()
+ },
+ )
+
+ async def _byok_enabled(self) -> bool:
+ """Whether BYOK is on. Read from the resolved web-client config so
+ discovery and the UI gate agree on the same value."""
+ from openhands.app_server.config import get_global_config
+
+ config = await get_global_config().web_client.get_web_client_config()
+ return config.feature_flags.allow_user_llm_configuration
+
+ async def _union_with_catalogue(
+ self, proxy_response: ModelsResponse
+ ) -> ModelsResponse:
+ """BYOK on: add the full SDK provider catalogue so users can pick any
+ provider and bring their own key (matches SaaS). Proxy models stay the
+ managed/verified set; catalogue models land unverified ("Other"). BYOK
+ off: return the managed proxy list unchanged."""
+ if not await self._byok_enabled():
+ return proxy_response
+ catalogue = get_supported_llm_models()
+ proxy_models = set(proxy_response.models)
+ extra = [
+ m
+ for m in catalogue.models
+ if not m.startswith(_OPENHANDS_PREFIX) and m not in proxy_models
+ ]
+ return ModelsResponse(
+ models=proxy_response.models + extra,
+ verified_models=proxy_response.verified_models,
+ verified_providers=proxy_response.verified_providers,
+ default_model=proxy_response.default_model,
+ hidden_models=proxy_response.hidden_models,
+ hidden_model_canonicals=proxy_response.hidden_model_canonicals,
+ )
+
+ def _is_model_verified(
+ self, model_name: str, name: str, models_response: ModelsResponse
+ ) -> bool:
+ # Managed proxy models are verified; the unioned SDK catalogue (BYOK)
+ # is not. Require the openhands/ prefix so a catalogue model whose bare
+ # name collides with a proxy one (openai/gpt-5 vs proxy gpt-5) isn't
+ # falsely verified.
+ return model_name.startswith(_OPENHANDS_PREFIX) and name in set(
+ models_response.verified_models
+ )
+
+ async def _get_models_response(
+ self,
+ verified_models: list[str] | None = None,
+ ) -> ModelsResponse:
+ cls = LiteLLMProxyModelService
+ response = cls._shared_response
+ if (
+ response is not None
+ and self._now() - cls._shared_fetched_at < CACHE_TTL_SECONDS
+ ):
+ return response
+
+ async with cls._fetch_lock:
+ # Re-check after acquiring the lock — a concurrent request may
+ # have refreshed the cache while this one was waiting.
+ response = cls._shared_response
+ if (
+ response is not None
+ and self._now() - cls._shared_fetched_at < CACHE_TTL_SECONDS
+ ):
+ return response
+
+ try:
+ (
+ model_names,
+ hidden_model_names,
+ hidden_model_canonicals,
+ ) = await self._fetch_proxy_model_names()
+ except Exception:
+ if response is not None:
+ # Serve the last-good result regardless of age. The next
+ # request retries because the timestamp is not refreshed.
+ _logger.warning(
+ 'Failed to fetch models from the LiteLLM proxy; '
+ 'serving the last successful result',
+ exc_info=True,
+ )
+ return response
+ _logger.error(
+ 'Failed to fetch models from the LiteLLM proxy and no '
+ 'previous result is cached; returning an empty model list',
+ exc_info=True,
+ )
+ # Not cached, so the next request retries immediately. Still
+ # union the catalogue so BYOK users can bring a key while the
+ # proxy is unreachable.
+ return await self._union_with_catalogue(self._build_response([]))
+
+ response = await self._union_with_catalogue(
+ self._build_response(
+ model_names, hidden_model_names, hidden_model_canonicals
+ )
+ )
+ cls._shared_response = response
+ cls._shared_fetched_at = self._now()
+ return response
+
+
+class LiteLLMProxyModelServiceInjector(LLMModelServiceInjector):
+ """Injector that provides the LiteLLM-proxy-backed model service.
+
+ Activate via the environment variable::
+
+ OH_LLM_MODEL_KIND=server.verified_models.litellm_proxy_model_router.LiteLLMProxyModelServiceInjector
+ """
+
+ async def inject(
+ self, state: InjectorState, request: Request | None = None
+ ) -> AsyncGenerator[LLMModelService, None]:
+ yield LiteLLMProxyModelService()
diff --git a/enterprise/tests/unit/test_verified_model/test_litellm_proxy_model_service.py b/enterprise/tests/unit/test_verified_model/test_litellm_proxy_model_service.py
new file mode 100644
index 0000000000..c9782381cb
--- /dev/null
+++ b/enterprise/tests/unit/test_verified_model/test_litellm_proxy_model_service.py
@@ -0,0 +1,525 @@
+"""Unit tests for the LiteLLM-proxy-backed model discovery service."""
+
+import logging
+
+import httpx
+import pytest
+from server.verified_models import litellm_proxy_model_router as router_module
+from server.verified_models.litellm_proxy_model_router import (
+ LiteLLMProxyModelService,
+ LiteLLMProxyModelServiceInjector,
+ _derive_default_model,
+)
+
+from openhands.app_server.utils.llm import ModelsResponse
+
+LOGGER_NAME = 'server.verified_models.litellm_proxy_model_router'
+
+HAPPY_PAYLOAD = {
+ 'data': [
+ {
+ 'model_name': 'claude-sonnet-4-5',
+ 'litellm_params': {'model': 'anthropic/claude-sonnet-4-5'},
+ 'model_info': {'openhands_default': True},
+ },
+ {
+ 'model_name': 'hidden-model',
+ 'litellm_params': {'model': 'openai/gpt-5'},
+ 'model_info': {
+ 'openhands_hidden': True,
+ 'openhands_canonical': 'claude-sonnet-4-5',
+ },
+ },
+ {
+ # Duplicate of the first entry — a load-balanced deployment.
+ 'model_name': 'claude-sonnet-4-5',
+ 'litellm_params': {'model': 'bedrock/claude-sonnet-4-5'},
+ 'model_info': {},
+ },
+ {
+ 'model_name': 'gpt-5',
+ 'litellm_params': {'model': 'openai/gpt-5'},
+ 'model_info': {},
+ },
+ {
+ # Entry without a model_name is skipped.
+ 'litellm_params': {'model': 'openai/gpt-4o'},
+ },
+ 'not-a-dict',
+ ]
+}
+
+
+class FakeResponse:
+ def __init__(self, payload, status_code: int = 200):
+ self._payload = payload
+ self.status_code = status_code
+
+ def raise_for_status(self):
+ if self.status_code >= 400:
+ raise httpx.HTTPStatusError(
+ f'HTTP {self.status_code}',
+ request=httpx.Request('GET', 'http://litellm.test/model/info'),
+ response=httpx.Response(self.status_code),
+ )
+
+ def json(self):
+ return self._payload
+
+
+def make_fake_client(response=None, error=None):
+ """Build a fake httpx.AsyncClient class that records calls."""
+
+ calls: list[dict] = []
+
+ class FakeAsyncClient:
+ def __init__(self, **kwargs):
+ self.init_kwargs = kwargs
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc_info):
+ return False
+
+ async def get(self, url, headers=None):
+ calls.append({'url': url, 'headers': headers or {}})
+ if error is not None:
+ raise error
+ return response
+
+ return FakeAsyncClient, calls
+
+
[email protected](autouse=True)
+def reset_cache():
+ LiteLLMProxyModelService._reset_cache()
+ yield
+ LiteLLMProxyModelService._reset_cache()
+
+
[email protected](autouse=True)
+def proxy_env(monkeypatch):
+ monkeypatch.setattr(router_module, 'LITE_LLM_API_URL', 'http://litellm.test')
+ monkeypatch.setattr(router_module, 'LITE_LLM_API_KEY', 'test-master-key')
+ monkeypatch.setattr(
+ router_module,
+ 'get_default_litellm_model',
+ lambda: 'litellm_proxy/claude-sonnet-4-5',
+ )
+
+
[email protected](autouse=True)
+def byok_off(monkeypatch):
+ """Default BYOK off so the proxy-only tests are unaffected; the union
+ tests opt in via ``byok_on``. (BYOK defaults *on* in real config, so
+ without this every test would hit the real web-client config lookup.)"""
+
+ async def _off(self):
+ return False
+
+ monkeypatch.setattr(LiteLLMProxyModelService, '_byok_enabled', _off)
+
+
+# A deterministic stand-in for the SDK catalogue. Two bare names collide with
+# the proxy's (``gpt-5``, ``claude-sonnet-4-5``) to exercise the verified-flag
+# guard; an ``openhands/``-prefixed entry must be dropped from the union.
+STUB_CATALOGUE = ModelsResponse(
+ models=[
+ 'anthropic/claude-sonnet-4-5',
+ 'openai/gpt-5',
+ 'openai/gpt-4o',
+ 'gemini/gemini-2.0-flash',
+ 'openhands/should-be-dropped',
+ ],
+ verified_models=['anthropic/claude-sonnet-4-5'],
+ verified_providers=['anthropic'],
+ default_model='anthropic/claude-sonnet-4-5',
+ hidden_models=[],
+ hidden_model_canonicals={},
+)
+
+
+def byok_on(monkeypatch, catalogue=STUB_CATALOGUE):
+ """Turn BYOK on and pin the SDK catalogue the union pulls from."""
+
+ async def _on(self):
+ return True
+
+ monkeypatch.setattr(LiteLLMProxyModelService, '_byok_enabled', _on)
+ monkeypatch.setattr(
+ router_module, 'get_supported_llm_models', lambda *a, **k: catalogue
+ )
+
+
+def fake_clock(monkeypatch):
+ """Controllable monotonic clock injected into the service."""
+ state = {'now': 1000.0}
+ monkeypatch.setattr(
+ LiteLLMProxyModelService, '_now', staticmethod(lambda: state['now'])
+ )
+ return state
+
+
+def install_client(monkeypatch, response=None, error=None):
+ fake_client, calls = make_fake_client(response=response, error=error)
+ monkeypatch.setattr(router_module.httpx, 'AsyncClient', fake_client)
+ return calls
+
+
+class TestHappyPath:
+ async def test_models_response_shape(self, monkeypatch):
+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ service = LiteLLMProxyModelService()
+
+ response = await service._get_models_response()
+
+ # Hidden models kept out of the visible list, duplicates removed,
+ # proxy order preserved, every model exposed under the public
+ # openhands/ prefix.
+ assert response.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']
+ assert response.verified_models == ['claude-sonnet-4-5', 'gpt-5']
+ assert response.verified_providers == ['openhands']
+ # Hidden alias routes are still reported so saved settings that
+ # reference them count as available.
+ assert response.hidden_models == ['openhands/hidden-model']
+ # The alias carries its canonical mapping (canonical is visible).
+ assert response.hidden_model_canonicals == {
+ 'openhands/hidden-model': 'openhands/claude-sonnet-4-5'
+ }
+ # litellm_proxy/ prefix translated to openhands/.
+ assert response.default_model == 'openhands/claude-sonnet-4-5'
+
+ assert len(calls) == 1
+ assert calls[0]['url'] == 'http://litellm.test/model/info'
+ assert calls[0]['headers']['Authorization'] == 'Bearer test-master-key'
+
+ async def test_search_llm_models_uses_proxy_models(self, monkeypatch):
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ service = LiteLLMProxyModelService()
+
+ page = await service.search_llm_models()
+
+ names = [(m.provider, m.name, m.hidden, m.canonical) for m in page.items]
+ assert names == [
+ ('openhands', 'claude-sonnet-4-5', False, None),
+ ('openhands', 'gpt-5', False, None),
+ # Hidden alias routes ride along flagged hidden=True so the
+ # frontend can exclude them from dropdown options while still
+ # treating saved settings that reference them as available;
+ # canonical names the visible model the alias routes to.
+ ('openhands', 'hidden-model', True, 'claude-sonnet-4-5'),
+ ]
+
+ async def test_hidden_only_when_all_duplicate_entries_hidden(self, monkeypatch):
+ # A load-balanced group is hidden only when every deployment that
+ # carries the name is hidden; one visible entry wins.
+ payload = {
+ 'data': [
+ {
+ 'model_name': 'mixed-model',
+ 'model_info': {'openhands_hidden': True},
+ },
+ {'model_name': 'mixed-model', 'model_info': {}},
+ {
+ 'model_name': 'legacy-alias',
+ 'model_info': {'openhands_hidden': True},
+ },
+ {
+ # Duplicate hidden entry — reported once.
+ 'model_name': 'legacy-alias',
+ 'model_info': {'openhands_hidden': True},
+ },
+ ]
+ }
+ install_client(monkeypatch, response=FakeResponse(payload))
+ service = LiteLLMProxyModelService()
+
+ response = await service._get_models_response()
+
+ assert response.models == ['openhands/mixed-model']
+ assert response.hidden_models == ['openhands/legacy-alias']
+ # No openhands_canonical tags anywhere -> no mappings.
+ assert response.hidden_model_canonicals == {}
+
+ async def test_canonical_skipped_when_not_visible(self, monkeypatch):
+ # A canonical tag pointing at a name the proxy does not serve
+ # visibly is dropped; a tag on a visible entry is ignored.
+ payload = {
+ 'data': [
+ {'model_name': 'real-model', 'model_info': {}},
+ {
+ 'model_name': 'alias-to-missing',
+ 'model_info': {
+ 'openhands_hidden': True,
+ 'openhands_canonical': 'removed-model',
+ },
+ },
+ {
+ 'model_name': 'alias-to-hidden',
+ 'model_info': {
+ 'openhands_hidden': True,
+ 'openhands_canonical': 'other-alias',
+ },
+ },
+ {
+ 'model_name': 'other-alias',
+ 'model_info': {'openhands_hidden': True},
+ },
+ ]
+ }
+ install_client(monkeypatch, response=FakeResponse(payload))
+ service = LiteLLMProxyModelService()
+
+ response = await service._get_models_response()
+
+ assert response.models == ['openhands/real-model']
+ assert response.hidden_models == [
+ 'openhands/alias-to-missing',
+ 'openhands/alias-to-hidden',
+ 'openhands/other-alias',
+ ]
+ assert response.hidden_model_canonicals == {}
+
+ page = await service.search_llm_models()
+ assert all(m.canonical is None for m in page.items)
+
+ async def test_canonical_mapped_for_visible_target(self, monkeypatch):
+ payload = {
+ 'data': [
+ {'model_name': 'real-model', 'model_info': {}},
+ {
+ 'model_name': 'legacy-alias',
+ 'model_info': {
+ 'openhands_hidden': True,
+ 'openhands_canonical': 'real-model',
+ },
+ },
+ {
+ # Hidden alias without a canonical tag -> no mapping.
+ 'model_name': 'untagged-alias',
+ 'model_info': {'openhands_hidden': True},
+ },
+ ]
+ }
+ install_client(monkeypatch, response=FakeResponse(payload))
+ service = LiteLLMProxyModelService()
+
+ response = await service._get_models_response()
+
+ assert response.hidden_model_canonicals == {
+ 'openhands/legacy-alias': 'openhands/real-model'
+ }
+
+ async def test_search_providers_only_openhands(self, monkeypatch):
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ service = LiteLLMProxyModelService()
+
+ page = await service.search_providers()
+
+ assert [(p.name, p.verified) for p in page.items] == [('openhands', True)]
+
+ async def test_no_auth_header_without_key(self, monkeypatch):
+ monkeypatch.setattr(router_module, 'LITE_LLM_API_KEY', None)
+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ service = LiteLLMProxyModelService()
+
+ await service._get_models_response()
+
+ assert 'Authorization' not in calls[0]['headers']
+
+
+class TestDefaultModelTranslation:
+ def test_litellm_proxy_prefix_translated(self, monkeypatch):
+ monkeypatch.setattr(
+ router_module, 'get_default_litellm_model', lambda: 'litellm_proxy/gpt-5'
+ )
+ assert _derive_default_model() == 'openhands/gpt-5'
+
+ def test_openhands_prefix_preserved(self, monkeypatch):
+ monkeypatch.setattr(
+ router_module, 'get_default_litellm_model', lambda: 'openhands/gpt-5'
+ )
+ assert _derive_default_model() == 'openhands/gpt-5'
+
+ def test_bare_name_prefixed(self, monkeypatch):
+ monkeypatch.setattr(router_module, 'get_default_litellm_model', lambda: 'gpt-5')
+ assert _derive_default_model() == 'openhands/gpt-5'
+
+
+class TestFailurePaths:
+ async def test_cold_failure_returns_empty_without_raising(
+ self, monkeypatch, caplog
+ ):
+ install_client(monkeypatch, error=httpx.ConnectError('boom'))
+ service = LiteLLMProxyModelService()
+
+ with caplog.at_level(logging.ERROR, logger=LOGGER_NAME):
+ response = await service._get_models_response()
+
+ assert response.models == []
+ assert response.verified_models == []
+ assert response.hidden_models == []
+ assert response.hidden_model_canonicals == {}
+ # The env-derived default is still communicated.
+ assert response.default_model == 'openhands/claude-sonnet-4-5'
+ assert any(
+ 'no previous result is cached' in record.message
+ for record in caplog.records
+ )
+
+ async def test_cold_failure_is_not_cached(self, monkeypatch):
+ install_client(monkeypatch, error=httpx.ConnectError('boom'))
+ service = LiteLLMProxyModelService()
+ assert (await service._get_models_response()).models == []
+
+ # The proxy recovers; the very next request succeeds (the failure
+ # result was not cached).
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ response = await LiteLLMProxyModelService()._get_models_response()
+ assert response.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']
+
+ async def test_http_error_status_returns_empty(self, monkeypatch):
+ install_client(monkeypatch, response=FakeResponse({}, status_code=500))
+ service = LiteLLMProxyModelService()
+
+ response = await service._get_models_response()
+
+ assert response.models == []
+
+ async def test_stale_cache_served_on_failure(self, monkeypatch, fake_clock, caplog):
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ first = await LiteLLMProxyModelService()._get_models_response()
+ assert first.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']
+
+ # Far beyond the TTL the proxy starts failing — the last-good result
+ # is served regardless of age.
+ fake_clock['now'] += 10_000.0
+ install_client(monkeypatch, error=httpx.ConnectError('boom'))
+ with caplog.at_level(logging.WARNING, logger=LOGGER_NAME):
+ second = await LiteLLMProxyModelService()._get_models_response()
+
+ assert second is first
+ assert any(
+ 'serving the last successful result' in record.message
+ for record in caplog.records
+ )
+
+
+class TestCacheTtl:
+ async def test_within_ttl_no_refetch(self, monkeypatch, fake_clock):
+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ first = await LiteLLMProxyModelService()._get_models_response()
+
+ fake_clock['now'] += router_module.CACHE_TTL_SECONDS - 1.0
+ second = await LiteLLMProxyModelService()._get_models_response()
+
+ assert second is first
+ assert len(calls) == 1
+
+ async def test_after_ttl_refetches(self, monkeypatch, fake_clock):
+ calls = install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+ await LiteLLMProxyModelService()._get_models_response()
+
+ fake_clock['now'] += router_module.CACHE_TTL_SECONDS + 1.0
+ updated_payload = {'data': [{'model_name': 'new-model', 'model_info': {}}]}
+ calls2 = install_client(monkeypatch, response=FakeResponse(updated_payload))
+ response = await LiteLLMProxyModelService()._get_models_response()
+
+ assert len(calls) == 1
+ assert len(calls2) == 1
+ assert response.models == ['openhands/new-model']
+
+
+class TestByokUnion:
+ """BYOK on unions the SDK catalogue so users can bring their own provider
+ (SaaS parity); BYOK off keeps the managed proxy list only."""
+
+ async def test_byok_off_ignores_catalogue(self, monkeypatch):
+ # Catalogue is available but BYOK is off (autouse default) -> proxy only.
+ monkeypatch.setattr(
+ router_module, 'get_supported_llm_models', lambda *a, **k: STUB_CATALOGUE
+ )
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+
+ response = await LiteLLMProxyModelService()._get_models_response()
+
+ assert response.models == ['openhands/claude-sonnet-4-5', 'openhands/gpt-5']
+
+ async def test_byok_on_unions_catalogue(self, monkeypatch):
+ byok_on(monkeypatch)
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+
+ response = await LiteLLMProxyModelService()._get_models_response()
+
+ # Managed proxy models first (order preserved), then catalogue extras;
+ # the openhands/-prefixed catalogue entry is dropped.
+ assert response.models == [
+ 'openhands/claude-sonnet-4-5',
+ 'openhands/gpt-5',
+ 'anthropic/claude-sonnet-4-5',
+ 'openai/gpt-5',
+ 'openai/gpt-4o',
+ 'gemini/gemini-2.0-flash',
+ ]
+ assert len(response.models) == len(set(response.models))
+ # Proxy stays the verified/default authority; catalogue opinions ignored.
+ assert response.verified_models == ['claude-sonnet-4-5', 'gpt-5']
+ assert response.verified_providers == ['openhands']
+ assert response.default_model == 'openhands/claude-sonnet-4-5'
+
+ async def test_byok_on_only_managed_models_verified(self, monkeypatch):
+ # Regression: a catalogue model whose bare name collides with a proxy
+ # one (openai/gpt-5 vs proxy gpt-5; anthropic/claude-sonnet-4-5 vs
+ # proxy claude-sonnet-4-5) must NOT be marked verified.
+ byok_on(monkeypatch)
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+
+ page = await LiteLLMProxyModelService().search_llm_models()
+ verified = {
+ (m.provider, m.name) for m in page.items if m.verified and not m.hidden
+ }
+
+ assert verified == {('openhands', 'claude-sonnet-4-5'), ('openhands', 'gpt-5')}
+
+ async def test_byok_on_exposes_catalogue_providers(self, monkeypatch):
+ byok_on(monkeypatch)
+ install_client(monkeypatch, response=FakeResponse(HAPPY_PAYLOAD))
+
+ page = await LiteLLMProxyModelService().search_providers()
+
+ # openhands stays the verified managed provider, listed first; catalogue
+ # providers ride along unverified so the picker shows for BYOK users.
+ assert [(p.name, p.verified) for p in page.items] == [
+ ('openhands', True),
+ ('anthropic', False),
+ ('gemini', False),
+ ('openai', False),
+ ]
+
+ async def test_byok_on_serves_catalogue_when_proxy_down(self, monkeypatch):
+ # Proxy unreachable + BYOK on: no managed models, but the catalogue is
+ # still offered so a BYOK user can bring their own key.
+ byok_on(monkeypatch)
+ install_client(monkeypatch, error=httpx.ConnectError('boom'))
+
+ response = await LiteLLMProxyModelService()._get_models_response()
+
+ assert response.models == [
+ 'anthropic/claude-sonnet-4-5',
+ 'openai/gpt-5',
+ 'openai/gpt-4o',
+ 'gemini/gemini-2.0-flash',
+ ]
+ assert response.verified_models == []
+
+
+class TestInjector:
+ async def test_injector_yields_service(self):
+ injector = LiteLLMProxyModelServiceInjector()
+ generator = injector.inject(None) # type: ignore[arg-type]
+ service = await generator.__anext__()
+ assert isinstance(service, LiteLLMProxyModelService)
+ with pytest.raises(StopAsyncIteration):
+ await generator.__anext__()
diff --git a/frontend/__tests__/components/modals/settings/model-selector.test.tsx b/frontend/__tests__/components/modals/settings/model-selector.test.tsx
index 215c0c115c..65484aa7c4 100644
--- a/frontend/__tests__/components/modals/settings/model-selector.test.tsx
+++ b/frontend/__tests__/components/modals/settings/model-selector.test.tsx
@@ -12,6 +12,9 @@ const mockProviders: LLMProvider[] = [
{ name: "openai", verified: true },
{ name: "azure", verified: false },
{ name: "vertex_ai", verified: false },
+ // Provider whose model list comes back empty (no entry in
+ // mockModelsByProvider) — used by the unavailable-model warning tests.
+ { name: "groq", verified: false },
];
const mockModelsByProvider: Record<string, LLMModel[]> = {
@@ -22,6 +25,10 @@ const mockModelsByProvider: Record<string, LLMModel[]> = {
azure: [
{ provider: "azure", name: "ada", verified: false },
{ provider: "azure", name: "gpt-35-turbo", verified: false },
+ // Served-but-not-promoted alias route (e.g. a legacy name a managed
+ // proxy keeps serving after a rename): never a dropdown option, but a
+ // saved setting referencing it still counts as available.
+ { provider: "azure", name: "legacy-alias", verified: false, hidden: true },
],
vertex_ai: [
{ provider: "vertex_ai", name: "chat-bison", verified: false },
@@ -108,6 +115,8 @@ describe("ModelSelector", () => {
expect(screen.getByText("ada")).toBeInTheDocument();
expect(screen.getByText("gpt-35-turbo")).toBeInTheDocument();
+ // Hidden alias routes are served by the backend but never promoted.
+ expect(screen.queryByText("legacy-alias")).not.toBeInTheDocument();
});
it("should call onChange when the provider and model change", async () => {
@@ -142,4 +151,74 @@ describe("ModelSelector", () => {
expect(container.firstChild).toHaveClass("w-full");
});
+
+ describe("unavailable model warning", () => {
+ it("shows a warning when the saved model is missing from a non-empty model list", async () => {
+ renderWithQuery(<ModelSelector currentModel="azure/removed-model" />);
+
+ await waitFor(() => {
+ expect(
+ screen.getByTestId("model-unavailable-warning"),
+ ).toBeInTheDocument();
+ });
+ });
+
+ it("does not show a warning when the saved model matches a hidden alias", async () => {
+ // "legacy-alias" is served by the backend (hidden=true) but is not a
+ // dropdown option — the saved setting still routes, so no warning.
+ renderWithQuery(<ModelSelector currentModel="azure/legacy-alias" />);
+
+ await waitFor(() => {
+ expect(screen.getByLabelText("LLM Provider")).toHaveValue("Azure");
+ });
+ expect(
+ screen.queryByTestId("model-unavailable-warning"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("does not show a warning when the saved model is in the model list", async () => {
+ renderWithQuery(<ModelSelector currentModel="azure/ada" />);
+
+ await waitFor(() => {
+ expect(screen.getByLabelText("LLM Model")).toHaveValue("ada");
+ });
+ expect(
+ screen.queryByTestId("model-unavailable-warning"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("does not show a warning when the provider's model list is empty", async () => {
+ // "groq" has no entry in mockModelsByProvider, so the hook returns []
+ // — an empty list must not cast doubt on the saved model.
+ renderWithQuery(<ModelSelector currentModel="groq/llama3-70b" />);
+
+ await waitFor(() => {
+ expect(screen.getByLabelText("LLM Provider")).toHaveValue("Groq");
+ });
+ expect(
+ screen.queryByTestId("model-unavailable-warning"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("clears the warning when the user picks an available model", async () => {
+ const user = userEvent.setup();
+ renderWithQuery(<ModelSelector currentModel="azure/removed-model" />);
+
+ await waitFor(() => {
+ expect(
+ screen.getByTestId("model-unavailable-warning"),
+ ).toBeInTheDocument();
+ });
+
+ const modelSelector = screen.getByLabelText("LLM Model");
+ await user.click(modelSelector);
+ await user.click(screen.getByText("ada"));
+
+ await waitFor(() => {
+ expect(
+ screen.queryByTestId("model-unavailable-warning"),
+ ).not.toBeInTheDocument();
+ });
+ });
+ });
});
diff --git a/frontend/__tests__/routes/llm-settings.test.tsx b/frontend/__tests__/routes/llm-settings.test.tsx
index 39f9f967c2..9bf34f3d37 100644
--- a/frontend/__tests__/routes/llm-settings.test.tsx
+++ b/frontend/__tests__/routes/llm-settings.test.tsx
@@ -3,6 +3,7 @@ import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { MemoryRouter } from "react-router";
+import { http, HttpResponse } from "msw";
import OrgProfilesService from "#/api/organization-service/org-profiles-service.api";
import { organizationService } from "#/api/organization-service/organization-service.api";
@@ -14,6 +15,7 @@ import {
MOCK_DEFAULT_USER_SETTINGS,
resetTestHandlersMockSettings,
} from "#/mocks/handlers";
+import { server } from "#/mocks/node";
import LlmSettingsScreen, { clientLoader } from "#/routes/llm-settings";
import { useSelectedOrganizationStore } from "#/stores/selected-organization-store";
import { Organization, OrganizationMember } from "#/types/org";
@@ -272,6 +274,7 @@ async function renderLlmSettingsScreen({
scope = "personal",
view = "form",
profile,
+ featureFlags,
}: {
appMode?: "oss" | "saas";
organizationId?: string;
@@ -289,6 +292,9 @@ async function renderLlmSettingsScreen({
// Override fields on the seeded edit profile when a test needs it to
// *differ* from the active settings.
profile?: Partial<LlmProfileSummary>;
+ // Web-client feature flags merged into the mocked /config payload, e.g.
+ // ``{ allow_user_llm_configuration: false }`` for managed OHE installs.
+ featureFlags?: Record<string, unknown>;
} = {}) {
const queryClient = new QueryClient({
defaultOptions: {
@@ -298,7 +304,10 @@ async function renderLlmSettingsScreen({
useSelectedOrganizationStore.setState({ organizationId });
mockUseConfig.mockReturnValue({
- data: { app_mode: appMode },
+ data: {
+ app_mode: appMode,
+ ...(featureFlags ? { feature_flags: featureFlags } : {}),
+ },
isLoading: false,
});
@@ -826,16 +835,33 @@ describe("LlmSettingsScreen", () => {
).not.toBeInTheDocument();
});
- it("hides the API key input for OpenHands provider in SaaS mode", async () => {
+ it("hides the API key input for OpenHands provider on enterprise cloud", async () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
- await renderLlmSettingsScreen({ appMode: "saas" });
+ await renderLlmSettingsScreen({
+ appMode: "saas",
+ featureFlags: { deployment_mode: "cloud" },
+ });
await screen.findByTestId("llm-settings-screen");
expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
expect(screen.getByTestId("openhands-api-key-help")).toBeInTheDocument();
});
+ it("hides the OpenHands API key help on self-hosted OHE", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+ await renderLlmSettingsScreen({
+ appMode: "saas",
+ featureFlags: { deployment_mode: "self_hosted" },
+ });
+
+ await screen.findByTestId("llm-settings-screen");
+ expect(
+ screen.queryByTestId("openhands-api-key-help"),
+ ).not.toBeInTheDocument();
+ });
+
it("shows the API key input for non-OpenHands providers in SaaS mode", async () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
buildSettings({
@@ -2755,9 +2781,7 @@ describe("LlmSettingsScreen", () => {
expect(screen.getByTestId("llm-model-input")).toHaveValue("");
// No provider selected yet, so the API key input isn't rendered (it
// appears once a key-taking provider is chosen).
- expect(
- screen.queryByTestId("llm-api-key-input"),
- ).not.toBeInTheDocument();
+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));
@@ -2790,9 +2814,7 @@ describe("LlmSettingsScreen", () => {
// rendering it only to remove it again when a managed provider is
// picked was jarring.
await screen.findByTestId("llm-settings-form-basic");
- expect(
- screen.queryByTestId("llm-api-key-input"),
- ).not.toBeInTheDocument();
+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
// Picking a key-taking provider reveals the input.
await selectProvider("OpenAI");
@@ -2801,9 +2823,7 @@ describe("LlmSettingsScreen", () => {
// The managed OpenHands provider keeps it hidden in SaaS mode (keys
// are auto-provisioned).
await selectProvider("OpenHands");
- expect(
- screen.queryByTestId("llm-api-key-input"),
- ).not.toBeInTheDocument();
+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
});
it("keeps Save disabled in the create form until a model is chosen", async () => {
@@ -2969,6 +2989,119 @@ describe("LlmSettingsScreen", () => {
});
});
+ it("hydrates the edit form with the canonical model when the profile stores a hidden alias", async () => {
+ // Legacy profile model "openhands/custom-llm" is a hidden alias that
+ // the catalog maps to the visible claude-sonnet model.
+ server.use(
+ http.get("/api/v1/config/models/search", () =>
+ HttpResponse.json({
+ items: [
+ {
+ provider: "openhands",
+ name: "claude-sonnet-4-5-20250929",
+ verified: true,
+ },
+ {
+ provider: "openhands",
+ name: "custom-llm",
+ verified: false,
+ hidden: true,
+ canonical: "claude-sonnet-4-5-20250929",
+ },
+ ],
+ next_page_id: null,
+ }),
+ ),
+ );
+ const saveSettingsSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ await renderLlmSettingsScreen({
+ appMode: "oss",
+ profile: {
+ name: "legacy-profile",
+ model: "openhands/custom-llm",
+ base_url: null,
+ },
+ });
+
+ await screen.findByTestId("llm-settings-form-basic");
+ await waitFor(() => {
+ expect(screen.getByTestId("llm-provider-input")).toHaveValue(
+ "OpenHands",
+ );
+ expect(screen.getByTestId("llm-model-input")).toHaveValue(
+ "claude-sonnet-4-5-20250929",
+ );
+ });
+ expect(
+ screen.queryByTestId("model-unavailable-warning"),
+ ).not.toBeInTheDocument();
+
+ // A pristine save persists the canonical id — deliberately migrating
+ // the profile off the legacy alias (both names route on the proxy).
+ await userEvent.click(screen.getByTestId("save-button"));
+ await waitFor(() => {
+ expect(saveSettingsSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ agent_settings_diff: expect.objectContaining({
+ llm: expect.objectContaining({
+ model: "openhands/claude-sonnet-4-5-20250929",
+ }),
+ }),
+ }),
+ );
+ });
+ });
+
+ it("keeps the stored alias when a hidden model has no canonical mapping", async () => {
+ server.use(
+ http.get("/api/v1/config/models/search", () =>
+ HttpResponse.json({
+ items: [
+ {
+ provider: "openhands",
+ name: "claude-sonnet-4-5-20250929",
+ verified: true,
+ },
+ // Hidden but with no canonical mapping — nothing to translate.
+ {
+ provider: "openhands",
+ name: "orphan-alias",
+ verified: false,
+ hidden: true,
+ },
+ ],
+ next_page_id: null,
+ }),
+ ),
+ );
+
+ await renderLlmSettingsScreen({
+ appMode: "oss",
+ profile: {
+ name: "orphan-profile",
+ model: "openhands/orphan-alias",
+ base_url: null,
+ },
+ });
+
+ await screen.findByTestId("llm-settings-form-basic");
+ await waitFor(() => {
+ expect(screen.getByTestId("llm-provider-input")).toHaveValue(
+ "OpenHands",
+ );
+ });
+ // Unchanged today-behavior: hidden aliases are never dropdown options,
+ // so the selection renders empty — and no unavailable badge, since the
+ // proxy still serves the alias.
+ expect(screen.getByTestId("llm-model-input")).toHaveValue("");
+ expect(
+ screen.queryByTestId("model-unavailable-warning"),
+ ).not.toBeInTheDocument();
+ });
+
it("opens edit on advanced with the profile's custom base URL while the active settings are plain", async () => {
vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
buildSettings({
@@ -3098,4 +3231,137 @@ describe("LlmSettingsScreen", () => {
);
});
});
+
+ describe("managed LLM configuration gating (allow_user_llm_configuration=false)", () => {
+ const MANAGED_FLAGS = { allow_user_llm_configuration: false };
+
+ it("hides BYOK inputs and lands on the model dropdown even when a custom base URL is saved", async () => {
+ // A saved custom base URL normally opens the advanced form with the
+ // custom-model + base-URL inputs. With BYOK disallowed the user lands
+ // on the managed dropdown instead — the saved settings themselves are
+ // untouched and keep working at runtime.
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({
+ llm_model: "openai/gpt-4o",
+ llm_base_url: "https://custom.example/v1",
+ agent_settings: {
+ llm: {
+ model: "openai/gpt-4o",
+ base_url: "https://custom.example/v1",
+ },
+ },
+ }),
+ );
+
+ await renderLlmSettingsScreen({
+ appMode: "oss",
+ featureFlags: MANAGED_FLAGS,
+ });
+
+ await screen.findByTestId("llm-settings-form-basic");
+ expect(screen.getByTestId("llm-provider-input")).toBeInTheDocument();
+ expect(screen.getByTestId("llm-model-input")).toBeInTheDocument();
+ expect(screen.getByTestId("save-button")).toBeInTheDocument();
+
+ expect(
+ screen.queryByTestId("llm-settings-form-advanced"),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByTestId("llm-custom-model-input"),
+ ).not.toBeInTheDocument();
+ expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();
+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
+ // No BYOK and no schema-driven advanced fields → no Advanced toggle.
+ expect(
+ screen.queryByTestId("sdk-section-advanced-toggle"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("suppresses the Advanced toggle when BYOK is off, even with schema-driven advanced fields", async () => {
+ // Without BYOK the LLM Advanced view (custom model + base URL) has
+ // nothing to show, so Basic and Advanced would be identical. The
+ // Advanced toggle is hidden entirely — even when the schema carries
+ // advanced fields that would otherwise surface it.
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettingsWithAdvancedToggle({
+ llm_model: "openai/gpt-4o",
+ agent_settings: { llm: { model: "openai/gpt-4o" } },
+ }),
+ );
+
+ await renderLlmSettingsScreen({
+ appMode: "oss",
+ featureFlags: MANAGED_FLAGS,
+ });
+
+ await screen.findByTestId("llm-settings-form-basic");
+
+ expect(
+ screen.queryByTestId("sdk-section-advanced-toggle"),
+ ).not.toBeInTheDocument();
+ expect(screen.getByTestId("llm-settings-form-basic")).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("llm-settings-form-advanced"),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByTestId("llm-custom-model-input"),
+ ).not.toBeInTheDocument();
+ expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();
+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
+ });
+
+ it("hides BYOK inputs on the org-defaults form in SaaS mode", async () => {
+ vi.spyOn(
+ organizationService,
+ "getOrganizationSettings",
+ ).mockResolvedValue(
+ buildSettings({
+ agent_settings: { llm: { model: "openai/gpt-4o" } },
+ }),
+ );
+
+ await renderLlmSettingsScreen({
+ appMode: "saas",
+ scope: "org",
+ featureFlags: MANAGED_FLAGS,
+ });
+
+ await screen.findByTestId("llm-settings-form-basic");
+ expect(screen.getByTestId("llm-provider-input")).toBeInTheDocument();
+ expect(screen.getByTestId("llm-model-input")).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("sdk-section-advanced-toggle"),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByTestId("llm-custom-model-input"),
+ ).not.toBeInTheDocument();
+ expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();
+ expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
+ });
+
+ it("keeps BYOK inputs when the flag is explicitly true", async () => {
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings(),
+ );
+
+ await renderLlmSettingsScreen({
+ appMode: "oss",
+ featureFlags: { allow_user_llm_configuration: true },
+ });
+
+ await screen.findByTestId("llm-settings-form-basic");
+ expect(screen.getByTestId("llm-api-key-input")).toBeInTheDocument();
+ expect(
+ screen.getByTestId("sdk-section-advanced-toggle"),
+ ).toBeInTheDocument();
+
+ await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));
+
+ expect(
+ screen.getByTestId("llm-settings-form-advanced"),
+ ).toBeInTheDocument();
+ expect(screen.getByTestId("llm-custom-model-input")).toBeInTheDocument();
+ expect(screen.getByTestId("base-url-input")).toBeInTheDocument();
+ });
+ });
});
diff --git a/frontend/src/api/config-service/config-service.types.ts b/frontend/src/api/config-service/config-service.types.ts
index dc8e7235bb..adfdd627b5 100644
--- a/frontend/src/api/config-service/config-service.types.ts
+++ b/frontend/src/api/config-service/config-service.types.ts
@@ -4,6 +4,14 @@ export interface LLMModel {
provider: string | null;
name: string;
verified: boolean;
+ /** Served but not promoted (e.g. a legacy alias route on a managed
+ * LiteLLM proxy): never offered as a dropdown option, yet a saved
+ * setting that references it still counts as available. Optional so
+ * older backends (no field) behave as before. */
+ hidden?: boolean;
+ /** Bare name of the visible model a hidden alias routes to (same
+ * provider); mirrors the backend LLMModelInfo.canonical contract. */
+ canonical?: string;
}
export interface LLMModelPage {
diff --git a/frontend/src/api/option-service/option.types.ts b/frontend/src/api/option-service/option.types.ts
index be92dcdee7..968e9fac44 100644
--- a/frontend/src/api/option-service/option.types.ts
+++ b/frontend/src/api/option-service/option.types.ts
@@ -17,6 +17,11 @@ export interface ModelsResponse {
verified_providers: string[];
/** Recommended default model id (e.g. ``openhands/claude-opus-4-5-20251101``). */
default_model: string;
+ /** ``provider/model`` strings the backend serves but does not promote
+ * (e.g. legacy alias routes on a managed LiteLLM proxy): not dropdown
+ * options, but saved settings referencing them still count as available.
+ * Optional so older backends (no field) behave as before. */
+ hidden_models?: string[];
}
export interface WebClientFeatureFlags {
@@ -31,6 +36,11 @@ export interface WebClientFeatureFlags {
/** Hide personal workspaces from the org list/selector for users who
* belong to at least one team org (OHE "org-only" installs). */
hide_personal_workspaces?: boolean;
+ /** When false, hide the BYOK editing UI (custom model, base URL, API key)
+ * in LLM settings — users only pick from the managed model dropdown.
+ * Defaults to true (absent ⇒ allowed) so SaaS/existing installs are
+ * unaffected. Saved BYOK settings keep working at runtime either way. */
+ allow_user_llm_configuration?: boolean;
enable_acp?: boolean;
deployment_mode?: DeploymentMode;
enable_onboarding: boolean;
diff --git a/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx
index 44dc9f958d..00c91ca334 100644
--- a/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx
+++ b/frontend/src/components/features/settings/sdk-settings/sdk-section-page.tsx
@@ -142,6 +142,7 @@ export function SdkSectionPage({
initialValueOverrides,
isSaveDisabled,
forceShowAdvancedView = false,
+ allowAdvancedView = true,
allowAllView = true,
trailingActions,
testId = "sdk-section-settings-screen",
@@ -192,6 +193,10 @@ export function SdkSectionPage({
// navigation button into the same row.
trailingActions?: React.ReactNode;
forceShowAdvancedView?: boolean;
+ // Master gate for the Advanced tier. When false the Advanced toggle never
+ // shows, even if the schema has advanced fields — e.g. the LLM page when
+ // BYOK is off, where Basic and Advanced would otherwise be identical.
+ allowAdvancedView?: boolean;
allowAllView?: boolean;
testId?: string;
}) {
@@ -276,8 +281,9 @@ export function SdkSectionPage({
);
const showAdvanced =
- forceShowAdvancedView ||
- resolvedSources.some((src) => hasAdvancedSettings(src.filteredSchema));
+ allowAdvancedView &&
+ (forceShowAdvancedView ||
+ resolvedSources.some((src) => hasAdvancedSettings(src.filteredSchema)));
const showAll =
allowAllView &&
resolvedSources.some((src) => hasMinorSettings(src.filteredSchema));
diff --git a/frontend/src/components/shared/modals/settings/model-selector.tsx b/frontend/src/components/shared/modals/settings/model-selector.tsx
index 4f00ef60d7..3aa4e33140 100644
--- a/frontend/src/components/shared/modals/settings/model-selector.tsx
+++ b/frontend/src/components/shared/modals/settings/model-selector.tsx
@@ -59,13 +59,35 @@ export function ModelSelector({
[providers],
);
- const verifiedModels = React.useMemo(
- () => providerModels.filter((m) => m.verified),
+ // Hidden models (e.g. legacy alias routes a managed proxy still serves
+ // after a rename) are never offered as dropdown options, but they do
+ // count as available for the saved-model check below.
+ const dropdownModels = React.useMemo(
+ () => providerModels.filter((m) => !m.hidden),
[providerModels],
);
+ const verifiedModels = React.useMemo(
+ () => dropdownModels.filter((m) => m.verified),
+ [dropdownModels],
+ );
const unverifiedModels = React.useMemo(
- () => providerModels.filter((m) => !m.verified),
- [providerModels],
+ () => dropdownModels.filter((m) => !m.verified),
+ [dropdownModels],
+ );
+
+ // Truthful-but-gentle signal that the displayed model no longer exists in
+ // the provider's model list (e.g. an admin removed it from a managed
+ // proxy). Only shown when the list actually loaded non-empty — a fetch
+ // error or an unknown provider must not cast doubt on a working config.
+ // Hidden models count as available: the proxy still serves them.
+ const isSelectedModelUnavailable = React.useMemo(
+ () =>
+ !!selectedModel &&
+ !isLoadingModels &&
+ !modelsError &&
+ providerModels.length > 0 &&
+ !providerModels.some((m) => m.name === selectedModel),
+ [selectedModel, isLoadingModels, modelsError, providerModels],
);
React.useEffect(() => {
@@ -79,6 +101,17 @@ export function ModelSelector({
}
}, [currentModel]);
+ // With a single provider (e.g. managed OHE's bundled proxy) there is nothing
+ // to pick — auto-select it so the picker below can be hidden.
+ React.useEffect(() => {
+ if (providers.length === 1 && !selectedProvider && !currentModel) {
+ const provider = providers[0].name;
+ setSelectedProvider(provider);
+ setLitellmId(`${provider}/`);
+ onChange?.(provider, null);
+ }
+ }, [providers, selectedProvider, currentModel]);
+
const handleChangeProvider = (provider: string) => {
setSelectedProvider(provider);
setSelectedModel(null);
@@ -111,56 +144,70 @@ export function ModelSelector({
wrapperClassName,
)}
>
- <fieldset className="flex flex-col gap-2.5 w-full">
- <label className={cn("text-sm", labelClassName)}>
- {t(I18nKey.LLM$PROVIDER)}
- </label>
- <Autocomplete
- data-testid="llm-provider-input"
- isRequired
- isVirtualized={false}
- name="llm-provider-input"
- isDisabled={isDisabled}
- aria-label={t(I18nKey.LLM$PROVIDER)}
- placeholder={t(I18nKey.LLM$SELECT_PROVIDER_PLACEHOLDER)}
- isClearable={false}
- onSelectionChange={(e) => {
- if (e?.toString()) handleChangeProvider(e.toString());
- }}
- onInputChange={(value) => !value && clear()}
- defaultSelectedKey={selectedProvider ?? undefined}
- selectedKey={selectedProvider}
- classNames={{
- popoverContent: "bg-tertiary rounded-xl border border-[#717888]",
- }}
- inputProps={{
- classNames: {
- inputWrapper:
- "bg-tertiary border border-[#717888] h-10 w-full rounded-sm p-2 placeholder:italic",
- },
- }}
- >
- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$VERIFIED)}>
- {verifiedProviders.map((provider) => (
- <AutocompleteItem
- data-testid={`provider-item-${provider.name}`}
- key={provider.name}
- >
- {mapProvider(provider.name)}
- </AutocompleteItem>
- ))}
- </AutocompleteSection>
- {unverifiedProviders.length > 0 ? (
- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$OTHERS)}>
- {unverifiedProviders.map((provider) => (
- <AutocompleteItem key={provider.name}>
+ {providers.length !== 1 ? (
+ <fieldset className="flex flex-col gap-2.5 w-full">
+ <label className={cn("text-sm", labelClassName)}>
+ {t(I18nKey.LLM$PROVIDER)}
+ </label>
+ <Autocomplete
+ data-testid="llm-provider-input"
+ isRequired
+ isVirtualized={false}
+ name="llm-provider-input"
+ isDisabled={isDisabled}
+ aria-label={t(I18nKey.LLM$PROVIDER)}
+ placeholder={t(I18nKey.LLM$SELECT_PROVIDER_PLACEHOLDER)}
+ isClearable={false}
+ onSelectionChange={(e) => {
+ if (e?.toString()) handleChangeProvider(e.toString());
+ }}
+ onInputChange={(value) => !value && clear()}
+ defaultSelectedKey={selectedProvider ?? undefined}
+ selectedKey={selectedProvider}
+ classNames={{
+ popoverContent: "bg-tertiary rounded-xl border border-[#717888]",
+ }}
+ inputProps={{
+ classNames: {
+ inputWrapper:
+ "bg-tertiary border border-[#717888] h-10 w-full rounded-sm p-2 placeholder:italic",
+ },
+ }}
+ >
+ <AutocompleteSection
+ title={
+ unverifiedProviders.length > 0
+ ? t(I18nKey.MODEL_SELECTOR$VERIFIED)
+ : undefined
+ }
+ >
+ {verifiedProviders.map((provider) => (
+ <AutocompleteItem
+ data-testid={`provider-item-${provider.name}`}
+ key={provider.name}
+ >
{mapProvider(provider.name)}
</AutocompleteItem>
))}
</AutocompleteSection>
- ) : null}
- </Autocomplete>
- </fieldset>
+ {unverifiedProviders.length > 0 ? (
+ <AutocompleteSection
+ title={
+ verifiedProviders.length > 0
+ ? t(I18nKey.MODEL_SELECTOR$OTHERS)
+ : undefined
+ }
+ >
+ {unverifiedProviders.map((provider) => (
+ <AutocompleteItem key={provider.name}>
+ {mapProvider(provider.name)}
+ </AutocompleteItem>
+ ))}
+ </AutocompleteSection>
+ ) : null}
+ </Autocomplete>
+ </fieldset>
+ ) : null}
{selectedProvider === "openhands" && isEnterpriseCloud && (
<HelpLink
@@ -202,13 +249,25 @@ export function ModelSelector({
},
}}
>
- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$VERIFIED)}>
+ <AutocompleteSection
+ title={
+ unverifiedModels.length > 0
+ ? t(I18nKey.MODEL_SELECTOR$VERIFIED)
+ : undefined
+ }
+ >
{verifiedModels.map((model) => (
<AutocompleteItem key={model.name}>{model.name}</AutocompleteItem>
))}
</AutocompleteSection>
{unverifiedModels.length > 0 ? (
- <AutocompleteSection title={t(I18nKey.MODEL_SELECTOR$OTHERS)}>
+ <AutocompleteSection
+ title={
+ verifiedModels.length > 0
+ ? t(I18nKey.MODEL_SELECTOR$OTHERS)
+ : undefined
+ }
+ >
{unverifiedModels.map((model) => (
<AutocompleteItem
data-testid={`model-item-${model.name}`}
@@ -225,6 +284,14 @@ export function ModelSelector({
{t(I18nKey.CONFIGURATION$ERROR_FETCH_MODELS)}
</p>
)}
+ {isSelectedModelUnavailable && (
+ <p
+ data-testid="model-unavailable-warning"
+ className="text-yellow-400 text-xs"
+ >
+ {t(I18nKey.SETTINGS$MODEL_NO_LONGER_AVAILABLE)}
+ </p>
+ )}
</fieldset>
</div>
);
diff --git a/frontend/src/hooks/query/use-provider-models.ts b/frontend/src/hooks/query/use-provider-models.ts
index d9dab7e58e..95e66387ca 100644
--- a/frontend/src/hooks/query/use-provider-models.ts
+++ b/frontend/src/hooks/query/use-provider-models.ts
@@ -1,4 +1,4 @@
-import { useQuery } from "@tanstack/react-query";
+import { queryOptions, useQuery } from "@tanstack/react-query";
import ConfigService from "#/api/config-service/config-service.api";
import type { LLMModel } from "#/api/config-service/config-service.types";
@@ -26,11 +26,18 @@ async function fetchPage(
return page.items;
}
-export const useProviderModels = (provider: string | null) =>
- useQuery({
+// Shared with imperative queryClient.fetchQuery callers so they reuse the
+// same cache entry (and staleness rules) as the hook.
+export const providerModelsQueryOptions = (provider: string | null) =>
+ queryOptions({
queryKey: ["config", "models", provider],
queryFn: () => fetchPage(provider!),
- enabled: !!provider,
staleTime: 1000 * 60 * 5,
gcTime: 1000 * 60 * 15,
});
+
+export const useProviderModels = (provider: string | null) =>
+ useQuery({
+ ...providerModelsQueryOptions(provider),
+ enabled: !!provider,
+ });
diff --git a/frontend/src/i18n/declaration.ts b/frontend/src/i18n/declaration.ts
index 73dfbb8353..8aa14eacff 100644
--- a/frontend/src/i18n/declaration.ts
+++ b/frontend/src/i18n/declaration.ts
@@ -384,6 +384,7 @@ export enum I18nKey {
SETTINGS$SEARCH_API_KEY = "SETTINGS$SEARCH_API_KEY",
SETTINGS$SEARCH_API_KEY_OPTIONAL = "SETTINGS$SEARCH_API_KEY_OPTIONAL",
SETTINGS$SEARCH_API_KEY_INSTRUCTIONS = "SETTINGS$SEARCH_API_KEY_INSTRUCTIONS",
+ SETTINGS$MODEL_NO_LONGER_AVAILABLE = "SETTINGS$MODEL_NO_LONGER_AVAILABLE",
SETTINGS$CUSTOM_MODEL = "SETTINGS$CUSTOM_MODEL",
GITHUB$CODE_NOT_IN_GITHUB = "GITHUB$CODE_NOT_IN_GITHUB",
GITHUB$START_FROM_SCRATCH = "GITHUB$START_FROM_SCRATCH",
diff --git a/frontend/src/i18n/translation.json b/frontend/src/i18n/translation.json
index f96871600b..ae1c9912af 100644
--- a/frontend/src/i18n/translation.json
+++ b/frontend/src/i18n/translation.json
@@ -4947,21 +4947,21 @@
"ca": "Aquesta configuració està gestionada per l'administrador de la teva organització"
},
"SETTINGS$ORG_DEFAULTS_INFO": {
- "en": "These organization defaults are applied first. Members can still add their own credentials or personal overrides where allowed.",
- "ja": "これらの組織のデフォルト設定が最初に適用されます。メンバーは許可されている範囲で、自分の認証情報や個人設定を追加できます。",
- "zh-CN": "这些组织默认设置会首先应用。成员仍然可以在允许的范围内添加自己的凭据或个人覆盖设置。",
- "zh-TW": "這些組織預設設定會首先套用。成員仍然可以在允許的範圍內新增自己的憑證或個人覆蓋設定。",
- "ko-KR": "이 조직 기본 설정이 먼저 적용됩니다. 구성원은 허용되는 범위 내에서 자체 자격 증명이나 개인 재정의를 추가할 수 있습니다.",
- "no": "Disse organisasjonsstandardene brukes først. Medlemmer kan fortsatt legge til egne legitimasjoner eller personlige overstyringer der det er tillatt.",
- "it": "Queste impostazioni predefinite dell'organizzazione vengono applicate per prime. I membri possono comunque aggiungere le proprie credenziali o sostituzioni personali dove consentito.",
- "pt": "Esses padrões da organização são aplicados primeiro. Os membros ainda podem adicionar suas próprias credenciais ou substituições pessoais onde permitido.",
- "es": "Estos valores predeterminados de la organización se aplican primero. Los miembros aún pueden agregar sus propias credenciales o anulaciones personales donde esté permitido.",
- "ar": "يتم تطبيق إعدادات المؤسسة الافتراضية أولاً. لا يزال بإمكان الأعضاء إضافة بيانات اعتمادهم أو تجاوزاتهم الشخصية حيثما كان ذلك مسموحًا.",
- "fr": "Ces paramètres par défaut de l'organisation sont appliqués en premier. Les membres peuvent toujours ajouter leurs propres identifiants ou remplacements personnels lorsque cela est autorisé.",
- "tr": "Bu organizasyon varsayılanları önce uygulanır. Üyeler izin verilen yerlerde kendi kimlik bilgilerini veya kişisel geçersiz kılmalarını ekleyebilir.",
- "de": "Diese Organisationsstandards werden zuerst angewendet. Mitglieder können weiterhin eigene Anmeldedaten oder persönliche Überschreibungen hinzufügen, wo dies erlaubt ist.",
- "uk": "Ці стандартні налаштування організації застосовуються першими. Учасники все ще можуть додавати власні облікові дані або особисті перевизначення там, де це дозволено.",
- "ca": "Aquests valors predeterminats de l'organització s'apliquen primer. Els membres encara poden afegir les seves pròpies credencials o substitucions personals on estigui permès."
+ "en": "These organization defaults are applied first. Members can apply personal overrides where allowed.",
+ "ja": "これらの組織のデフォルト設定が最初に適用されます。メンバーは許可されている範囲で個人設定を適用できます。",
+ "zh-CN": "这些组织默认设置会首先应用。成员可以在允许的范围内应用个人覆盖设置。",
+ "zh-TW": "這些組織預設設定會首先套用。成員可以在允許的範圍內套用個人覆蓋設定。",
+ "ko-KR": "이 조직 기본 설정이 먼저 적용됩니다. 구성원은 허용되는 범위 내에서 개인 재정의를 적용할 수 있습니다.",
+ "no": "Disse organisasjonsstandardene brukes først. Medlemmer kan bruke personlige overstyringer der det er tillatt.",
+ "it": "Queste impostazioni predefinite dell'organizzazione vengono applicate per prime. I membri possono applicare sostituzioni personali dove consentito.",
+ "pt": "Esses padrões da organização são aplicados primeiro. Os membros podem aplicar substituições pessoais onde permitido.",
+ "es": "Estos valores predeterminados de la organización se aplican primero. Los miembros pueden aplicar anulaciones personales donde esté permitido.",
+ "ar": "يتم تطبيق إعدادات المؤسسة الافتراضية أولاً. يمكن للأعضاء تطبيق التجاوزات الشخصية حيثما كان ذلك مسموحًا.",
+ "fr": "Ces paramètres par défaut de l'organisation sont appliqués en premier. Les membres peuvent appliquer des remplacements personnels lorsque cela est autorisé.",
+ "tr": "Bu organizasyon varsayılanları önce uygulanır. Üyeler izin verilen yerlerde kişisel geçersiz kılmaları uygulayabilir.",
+ "de": "Diese Organisationsstandards werden zuerst angewendet. Mitglieder können persönliche Überschreibungen anwenden, wo dies erlaubt ist.",
+ "uk": "Ці стандартні налаштування організації застосовуються першими. Учасники можуть застосовувати особисті перевизначення там, де це дозволено.",
+ "ca": "Aquests valors predeterminats de l'organització s'apliquen primer. Els membres poden aplicar substitucions personals on estigui permès."
},
"SETTINGS$PERSONAL_AGENT_INFO": {
"en": "These settings only affect your own work. Organization defaults still apply unless you override them here.",
@@ -6527,6 +6527,23 @@
"uk": "Отримайте свій ключ API від Tavily",
"ca": "Obteniu la vostra clau d'API a Tavily"
},
+ "SETTINGS$MODEL_NO_LONGER_AVAILABLE": {
+ "en": "No longer available",
+ "ja": "現在は利用できません",
+ "zh-CN": "已不再可用",
+ "zh-TW": "已不再可用",
+ "ko-KR": "더 이상 사용할 수 없음",
+ "de": "Nicht mehr verfügbar",
+ "no": "Ikke lenger tilgjengelig",
+ "it": "Non più disponibile",
+ "pt": "Não está mais disponível",
+ "es": "Ya no está disponible",
+ "ar": "لم يعد متاحًا",
+ "fr": "N'est plus disponible",
+ "tr": "Artık mevcut değil",
+ "uk": "Більше недоступна",
+ "ca": "Ja no està disponible"
+ },
"SETTINGS$CUSTOM_MODEL": {
"en": "Custom Model",
"ja": "カスタムモデル",
diff --git a/frontend/src/routes/llm-settings.tsx b/frontend/src/routes/llm-settings.tsx
index ddb1c7c108..c380d7bc2d 100644
--- a/frontend/src/routes/llm-settings.tsx
+++ b/frontend/src/routes/llm-settings.tsx
@@ -1,4 +1,5 @@
import React from "react";
+import { useQueryClient } from "@tanstack/react-query";
import { useSearchParams } from "react-router";
import { useTranslation } from "react-i18next";
import { FaChevronLeft } from "react-icons/fa6";
@@ -45,7 +46,9 @@ import { LlmProfilesManager } from "#/components/features/settings/llm-profiles-
import { OrgLlmProfilesManager } from "#/components/features/settings/org-llm-profiles-manager";
import { ProfileNameInput } from "#/components/features/settings/profile-name-input";
import { Typography } from "#/ui/typography";
+import { providerModelsQueryOptions } from "#/hooks/query/use-provider-models";
import { useOrgTypeAndAccess } from "#/hooks/use-org-type-and-access";
+import { useAppMode } from "#/hooks/use-app-mode";
import { useMe } from "#/hooks/query/use-me";
import { usePermission } from "#/hooks/organizations/use-permissions";
@@ -111,6 +114,7 @@ export function LlmSettingsScreen({
}) {
const { t } = useTranslation();
const [searchParams, setSearchParams] = useSearchParams();
+ const queryClient = useQueryClient();
const { data: settings } = useSettings(scope);
const { data: schema } = useAgentSettingsSchema(
@@ -185,6 +189,14 @@ export function LlmSettingsScreen({
);
const isSaasMode = config?.app_mode === "saas";
+ const { isEnterpriseCloud } = useAppMode();
+
+ // OHE installs can disable BYOK via OH_ALLOW_USER_LLM_CONFIGURATION; absent
+ // (SaaS / existing installs) means allowed. This hides the *editing* UI for
+ // custom model / base URL / API key only — saved BYOK settings keep working
+ // at runtime, and the managed model dropdown stays fully functional.
+ const allowUserLlmConfiguration =
+ config?.feature_flags?.allow_user_llm_configuration !== false;
React.useEffect(() => {
// An open profile form owns the provider selection (blank for create,
@@ -222,6 +234,12 @@ export function LlmSettingsScreen({
currentSettings: Settings,
filteredSchema: SettingsSchema,
): SettingsView => {
+ // Without BYOK there is nothing for the advanced/all tiers to reveal in
+ // the custom header, so always land on the managed model dropdown.
+ if (!allowUserLlmConfiguration) {
+ return "basic";
+ }
+
// A hint set by the Profiles mirror-strip beats every other rule —
// the user explicitly asked for this tier when leaving profiles.
if (initialViewHint) {
@@ -272,7 +290,14 @@ export function LlmSettingsScreen({
return hasCustomBaseUrl ? "all" : "basic";
},
- [editingProfile, initialViewHint, isSaasMode, profileFormMode, scope],
+ [
+ allowUserLlmConfiguration,
+ editingProfile,
+ initialViewHint,
+ isSaasMode,
+ profileFormMode,
+ scope,
+ ],
);
const buildHeader = React.useCallback(
@@ -292,7 +317,12 @@ export function LlmSettingsScreen({
: derivedProvider;
const shouldUseOpenHandsKey =
isSaasMode && activeProvider === "openhands";
- const showOpenHandsApiKeyHelp = modelValue.startsWith("openhands/");
+ // The OpenHands key help links to OpenHands Cloud keys/pricing — only
+ // meaningful on enterprise cloud, not self-hosted managed installs.
+ const showOpenHandsApiKeyHelp =
+ isEnterpriseCloud &&
+ modelValue.startsWith("openhands/") &&
+ allowUserLlmConfiguration;
// While editing, the set-but-unfetchable key indicator must reflect
// the clicked profile, not whichever profile is currently active.
const apiKeySet =
@@ -301,6 +331,12 @@ export function LlmSettingsScreen({
: settings?.llm_api_key_set;
const renderApiKeyInput = (testId: string, helpTestId: string) => {
+ // Managed installs: the admin owns provider keys on the bundled
+ // proxy; users never enter one.
+ if (!allowUserLlmConfiguration) {
+ return null;
+ }
+
if (shouldUseOpenHandsKey) {
return null;
}
@@ -361,7 +397,7 @@ export function LlmSettingsScreen({
/>
) : null}
- {view === "basic" ? (
+ {view === "basic" || !allowUserLlmConfiguration ? (
<div
className="flex flex-col gap-6"
data-testid="llm-settings-form-basic"
@@ -434,6 +470,7 @@ export function LlmSettingsScreen({
);
},
[
+ allowUserLlmConfiguration,
editingProfile,
infoMessageKey,
isSaasMode,
@@ -608,22 +645,52 @@ export function LlmSettingsScreen({
scope,
]);
- const openForm = (
+ // Legacy profiles can store a hidden catalog alias (e.g. a pre-rename
+ // proxy route). When the alias maps to a visible model, hydrate the edit
+ // form with that canonical id so the dropdown shows a real selection.
+ const resolveCanonicalModel = async (model: string): Promise<string> => {
+ const { provider, model: modelName } = extractModelAndProvider(model);
+ if (!provider) return model;
+ try {
+ const models = await queryClient.fetchQuery(
+ providerModelsQueryOptions(provider),
+ );
+ const match = models.find((m) => m.name === modelName);
+ if (match?.hidden && match.canonical) {
+ return `${provider}/${match.canonical}`;
+ }
+ } catch {
+ // Catalog unavailable — open with the stored model, exactly as today.
+ }
+ return model;
+ };
+
+ const openForm = async (
view: SettingsView | null,
profile: LlmProfileSummary | null = null,
) => {
// The profiles list passes the profile only when editing; Add Profile
// opens a blank create form.
- const isEdit = profile !== null;
+ let editProfile = profile;
+ if (editProfile?.model) {
+ // Resolved *before* the form opens: SdkSectionPage re-hydrates (and
+ // resets dirty state) whenever the initial-value overrides change, so
+ // a post-mount translation could clobber in-progress user edits.
+ const canonicalModel = await resolveCanonicalModel(editProfile.model);
+ if (canonicalModel !== editProfile.model) {
+ editProfile = { ...editProfile, model: canonicalModel };
+ }
+ }
+ const isEdit = editProfile !== null;
setProfileFormMode(isEdit ? "edit" : "create");
- setEditingProfile(profile);
- setProfileName(profile?.name ?? "");
- setInitialProfileName(profile?.name ?? "");
+ setEditingProfile(editProfile);
+ setProfileName(editProfile?.name ?? "");
+ setInitialProfileName(editProfile?.name ?? "");
setInitialViewHint(view);
// Blank for create; the edited profile's provider for edit.
setSelectedProvider(
- profile?.model
- ? extractModelAndProvider(profile.model).provider || null
+ editProfile?.model
+ ? extractModelAndProvider(editProfile.model).provider || null
: null,
);
setShowProfiles(false);
@@ -741,7 +808,10 @@ export function LlmSettingsScreen({
values["llm.model"].trim().length > 0
)
}
- forceShowAdvancedView
+ // Advanced (custom model + base URL) only exists under BYOK; gate the
+ // toggle on it so Basic/Advanced aren't identical when BYOK is off.
+ forceShowAdvancedView={allowUserLlmConfiguration}
+ allowAdvancedView={allowUserLlmConfiguration}
allowAllView={!isSaasMode}
testId="llm-settings-screen"
/>
diff --git a/openhands/app_server/config_api/config_models.py b/openhands/app_server/config_api/config_models.py
index e725e1a953..a435b744a4 100644
--- a/openhands/app_server/config_api/config_models.py
+++ b/openhands/app_server/config_api/config_models.py
@@ -20,6 +20,23 @@ class LLMModel(BaseModel):
verified: bool = Field(
default=False, description='Whether the model is verified by OpenHands'
)
+ hidden: bool = Field(
+ default=False,
+ description=(
+ 'Whether the model is served but not promoted: it must not be '
+ 'offered as a dropdown option, yet an already-saved setting '
+ 'referencing it is still valid (e.g. a legacy alias route on a '
+ 'managed LiteLLM proxy)'
+ ),
+ )
+ canonical: str | None = Field(
+ default=None,
+ description=(
+ 'For a hidden model only: the name of the visible model (same '
+ 'provider) this one aliases, so clients can display a saved '
+ 'hidden model under its canonical name'
+ ),
+ )
class LLMModelPage(BaseModel):
diff --git a/openhands/app_server/config_api/default_llm_model_service.py b/openhands/app_server/config_api/default_llm_model_service.py
index ef90317605..093991aab1 100644
--- a/openhands/app_server/config_api/default_llm_model_service.py
+++ b/openhands/app_server/config_api/default_llm_model_service.py
@@ -6,7 +6,7 @@ in-memory so that the router stays thin.
"""
import logging
-from typing import Any, AsyncGenerator
+from typing import Any, AsyncGenerator, Callable
import httpx
from fastapi import Request
@@ -40,21 +40,48 @@ _VERIFIED_MODEL_SET: set[str] = {
}
-def _to_llm_models(models_response: ModelsResponse) -> list[LLMModel]:
- """Convert raw model strings into ``LLMModel`` objects with verified flags."""
+def _to_llm_models(
+ models_response: ModelsResponse,
+ is_verified: Callable[[str, str, ModelsResponse], bool] | None = None,
+) -> list[LLMModel]:
+ """Convert raw model strings into ``LLMModel`` objects with verified flags.
+
+ Hidden models (served by the backend but not promoted, e.g. legacy alias
+ routes on a managed LiteLLM proxy) are appended after the visible ones
+ with ``hidden=True`` so clients can keep them out of dropdown options
+ while still treating saved settings that reference them as available.
+ A hidden model with a known canonical mapping carries the visible model
+ name it aliases in ``canonical``.
+ """
results: list[LLMModel] = []
- for model_name in models_response.models:
+ flagged_models = [(m, False) for m in models_response.models] + [
+ (m, True) for m in models_response.hidden_models
+ ]
+ for model_name, hidden in flagged_models:
parts = model_name.split('/', 1)
if len(parts) == 2:
provider, name = parts
else:
provider = None
name = parts[0]
+ canonical = None
+ if hidden:
+ canonical_full = models_response.hidden_model_canonicals.get(model_name)
+ if canonical_full:
+ # Same bare-name convention as ``name`` — the alias and its
+ # canonical model always share the provider.
+ canonical = canonical_full.split('/', 1)[-1]
results.append(
LLMModel(
provider=provider,
name=name,
- verified=model_name in _VERIFIED_MODEL_SET,
+ verified=(
+ is_verified(model_name, name, models_response)
+ if is_verified is not None
+ else model_name in _VERIFIED_MODEL_SET
+ ),
+ hidden=hidden,
+ canonical=canonical,
)
)
return results
@@ -153,6 +180,13 @@ class DefaultLLMModelService(LLMModelService):
)
return self._cached_response
+ def _is_model_verified(
+ self, model_name: str, name: str, models_response: ModelsResponse
+ ) -> bool:
+ """Whether a model is shown as "verified". Default is the static SDK
+ catalogue; subclasses (e.g. the managed proxy) override this."""
+ return model_name in _VERIFIED_MODEL_SET
+
# ------------------------------------------------------------------
# LLMModelService interface
# ------------------------------------------------------------------
@@ -167,7 +201,7 @@ class DefaultLLMModelService(LLMModelService):
limit: int = 50,
) -> LLMModelPage:
raw = await self._get_models_response()
- models = _to_llm_models(raw)
+ models = _to_llm_models(raw, self._is_model_verified)
if query is not None:
query_lower = query.lower()
diff --git a/openhands/app_server/utils/llm.py b/openhands/app_server/utils/llm.py
index 8f9b78f3c8..324c857392 100644
--- a/openhands/app_server/utils/llm.py
+++ b/openhands/app_server/utils/llm.py
@@ -81,12 +81,24 @@ class ModelsResponse(BaseModel):
* ``verified_providers`` — provider names shown in the "Verified"
section of the model selector.
* ``default_model`` — the recommended default model id.
+ * ``hidden_models`` — ``provider/model`` strings that the backend still
+ serves but does not promote: they must not be offered as dropdown
+ options, yet an already-saved setting referencing one is still valid
+ (e.g. legacy alias routes on a managed LiteLLM proxy). Default empty,
+ so SaaS / default discovery behavior is unchanged.
+ * ``hidden_model_canonicals`` — maps a hidden ``provider/model`` string
+ to the visible ``provider/model`` it aliases, so clients can display a
+ saved hidden model under its canonical name. Only mappings whose
+ target is in ``models`` are included. Default empty, so SaaS / default
+ discovery behavior is unchanged.
"""
models: list[str]
verified_models: list[str]
verified_providers: list[str]
default_model: str
+ hidden_models: list[str] = []
+ hidden_model_canonicals: dict[str, str] = {}
def is_openhands_model(model: str | None) -> bool:
diff --git a/openhands/app_server/web_client/default_web_client_config_injector.py b/openhands/app_server/web_client/default_web_client_config_injector.py
index ed625cda7b..c73db026dc 100644
--- a/openhands/app_server/web_client/default_web_client_config_injector.py
+++ b/openhands/app_server/web_client/default_web_client_config_injector.py
@@ -163,6 +163,9 @@ def _get_feature_flags() -> WebClientFeatureFlags:
HIDE_PERSONAL_WORKSPACES, ENABLE_ACP, and OH_ENABLE_ONBOARDING from
environment. Each flag is True only if the corresponding env var is
exactly 'true', otherwise False.
+
+ OH_ALLOW_USER_LLM_CONFIGURATION is the exception: it defaults to 'true'
+ when unset so SaaS and existing installs keep the BYOK editing UI.
"""
return WebClientFeatureFlags(
enable_billing=os.getenv('ENABLE_BILLING', 'false') == 'true',
@@ -175,6 +178,10 @@ def _get_feature_flags() -> WebClientFeatureFlags:
hide_integrations_page=os.getenv('HIDE_INTEGRATIONS_PAGE', 'false') == 'true',
hide_personal_workspaces=os.getenv('HIDE_PERSONAL_WORKSPACES', 'false')
== 'true',
+ allow_user_llm_configuration=os.getenv(
+ 'OH_ALLOW_USER_LLM_CONFIGURATION', 'true'
+ )
+ == 'true',
enable_acp=os.getenv('ENABLE_ACP', 'false') == 'true',
enable_onboarding=os.getenv('OH_ENABLE_ONBOARDING', 'false') == 'true',
)
diff --git a/openhands/app_server/web_client/web_client_models.py b/openhands/app_server/web_client/web_client_models.py
index 63472f5591..521736cea2 100644
--- a/openhands/app_server/web_client/web_client_models.py
+++ b/openhands/app_server/web_client/web_client_models.py
@@ -26,6 +26,13 @@ class WebClientFeatureFlags(BaseModel):
# workspace users see. UI-level only — the orgs API still returns
# personal orgs, and disabling the flag restores them.
hide_personal_workspaces: bool = False
+ # When false, the web client hides the BYOK editing UI (custom model
+ # string, base URL, and API key inputs) in LLM settings, leaving only the
+ # managed model dropdown. Used by OHE installs where admins curate the
+ # model list on the bundled LiteLLM proxy. Defaults to True so SaaS and
+ # existing installs are unaffected. UI-level only — previously saved BYOK
+ # settings keep working at runtime.
+ allow_user_llm_configuration: bool = True
enable_acp: bool = False
deployment_mode: DeploymentMode | None = None
enable_onboarding: bool = False
diff --git a/tests/unit/app_server/test_default_web_client_config_injector.py b/tests/unit/app_server/test_default_web_client_config_injector.py
index 7a5755eee5..da92f66d65 100644
--- a/tests/unit/app_server/test_default_web_client_config_injector.py
+++ b/tests/unit/app_server/test_default_web_client_config_injector.py
@@ -216,6 +216,40 @@ class TestGetFeatureFlags:
result = _get_feature_flags()
assert result.enable_linear is True
+ def test_allow_user_llm_configuration_true_when_env_var_unset(self):
+ """OH_ALLOW_USER_LLM_CONFIGURATION defaults to True when unset.
+
+ Critical: SaaS and existing installs never set this env var, so the
+ BYOK editing UI must stay visible for them.
+ """
+ from openhands.app_server.web_client.default_web_client_config_injector import (
+ _get_feature_flags,
+ )
+
+ with patch.dict(os.environ, {}, clear=True):
+ result = _get_feature_flags()
+ assert result.allow_user_llm_configuration is True
+
+ def test_allow_user_llm_configuration_true_when_env_var_true(self):
+ """When OH_ALLOW_USER_LLM_CONFIGURATION is 'true', the flag is True."""
+ from openhands.app_server.web_client.default_web_client_config_injector import (
+ _get_feature_flags,
+ )
+
+ with patch.dict(os.environ, {'OH_ALLOW_USER_LLM_CONFIGURATION': 'true'}):
+ result = _get_feature_flags()
+ assert result.allow_user_llm_configuration is True
+
+ def test_allow_user_llm_configuration_false_when_env_var_false(self):
+ """When OH_ALLOW_USER_LLM_CONFIGURATION is 'false', the flag is False."""
+ from openhands.app_server.web_client.default_web_client_config_injector import (
+ _get_feature_flags,
+ )
+
+ with patch.dict(os.environ, {'OH_ALLOW_USER_LLM_CONFIGURATION': 'false'}):
+ result = _get_feature_flags()
+ assert result.allow_user_llm_configuration is False
+
def test_multiple_flags_can_be_set(self):
"""Multiple feature flags can be enabled simultaneously."""
from openhands.app_server.web_client.default_web_client_config_injector import (
diff --git a/tests/unit/app_server/test_llm_model_service.py b/tests/unit/app_server/test_llm_model_service.py
index bb48b1063a..3db824bd24 100644
--- a/tests/unit/app_server/test_llm_model_service.py
+++ b/tests/unit/app_server/test_llm_model_service.py
@@ -11,8 +11,10 @@ from openhands.app_server.config_api.config_models import (
from openhands.app_server.config_api.default_llm_model_service import (
DefaultLLMModelService,
DefaultLLMModelServiceInjector,
+ _to_llm_models,
)
from openhands.app_server.config_api.llm_model_service import LLMModelService
+from openhands.app_server.utils.llm import ModelsResponse
class TestDefaultLLMModelServiceSearchModels:
@@ -173,6 +175,42 @@ class TestDefaultLLMModelServiceSearchModels:
]
+class TestToLLMModelsHiddenCanonical:
+ """Hidden models and their canonical mappings flow into LLMModel items."""
+
+ def test_canonical_set_only_on_mapped_hidden_models(self):
+ response = ModelsResponse(
+ models=['openhands/real-model'],
+ verified_models=['real-model'],
+ verified_providers=['openhands'],
+ default_model='openhands/real-model',
+ hidden_models=['openhands/legacy-alias', 'openhands/untagged-alias'],
+ hidden_model_canonicals={'openhands/legacy-alias': 'openhands/real-model'},
+ )
+
+ by_name = {m.name: m for m in _to_llm_models(response)}
+
+ assert by_name['real-model'].hidden is False
+ assert by_name['real-model'].canonical is None
+ assert by_name['legacy-alias'].hidden is True
+ # Canonical is reported as a bare model name, like ``name``.
+ assert by_name['legacy-alias'].canonical == 'real-model'
+ assert by_name['untagged-alias'].hidden is True
+ assert by_name['untagged-alias'].canonical is None
+
+ def test_defaults_empty_no_hidden_items(self):
+ response = ModelsResponse(
+ models=['openhands/real-model'],
+ verified_models=['real-model'],
+ verified_providers=['openhands'],
+ default_model='openhands/real-model',
+ )
+
+ models = _to_llm_models(response)
+
+ assert all(not m.hidden and m.canonical is None for m in models)
+
+
class TestDefaultLLMModelServiceSearchProviders:
"""Test suite for DefaultLLMModelService.search_providers."""