Repository navigation
Improve Gemini provider setup UX: unclear model discovery dependency causes misleading “model sync failed” state #4075
Description
Activity
리뷰 · 우선순위 46 / 80
설명
이 이슈는 Gemini(Google) 제공자를 붙일 때 실시간 모델 발견(Discover models from provider) 과 수동 커스텀 모델 추가가 서로 다른 화면에 있어서, 발견이 실패하면 “API가 망가졌다”처럼 보이지만 실제로는 설정 토글 문제라는 UX 보고입니다. 작성자 wbpluto, 라벨
enhancement+catalog. 재현 흐름은 (1) Provider에 Gemini API 키·엔드포인트(https://generativelanguage.googleapis.com)를 넣고, (2) Models 페이지에서gemini-3.8-flash를 수동 추가한 뒤, (3) 제공자 쪽에 “发现失败 / Discovery failed”가 떠서 모델이 쓸 수 없는 것처럼 보이고, (4) Provider Settings에서 발견을 끄면 수동 모델이 정상 동작한다는 것입니다. 지금 로컬devHEAD는8026405d9(#4067 wp7 stop 거절 사유), package 2.49.0입니다. types/config 분할·preview·2.49 tip 열차와는 축이 다릅니다.HEAD에서 동작이 이 보고와 맞는지 보면, 맞습니다. 관리 API
GET /api/providers는liveModels: p.liveModels !== false로 보냅니다(src/server/management/provider-routes.ts). 즉 값이 없으면 발견 ON이 기본입니다. GUI Provider Settings도 같은 규칙입니다(gui/src/components/provider-workspace/ProviderSettings.tsx:item.liveModels !== false). 토글 라벨은 i18npws.liveModels/ 중국어 “从提供方发现模型”이고, 설명(pws.liveModelsDesc)에 “끄면 정적/설정 모델만 쓴다”고 이미 적혀 있습니다. 문제는 그 토글이 Providers → 해당 제공자 Settings에만 있고, 실패 배지는 Models 쪽에 뜬다는 점입니다.Models 쪽 실패 UI도 HEAD에 그대로 있습니다.
gui/src/pages/Models.tsx는liveModels && discovery?.status === "failed"일 때 호박색 배지models.discoveryFailedBadge(“发现失败”)만 달고,title에 HTTP/네트워크/차단 등 이유를 넣습니다(discoveryFailureLabelingui/src/pages/models-shared.ts). 제공자 그룹이 비어 있을 때만EmptyProviderHint가 “打开提供方设置” 링크로 Providers로 보냅니다(gui/src/pages/models-provider-hints.tsx). 작성자처럼 커스텀 모델을 이미 넣은 상태에서는 빈 목록 힌트가 안 나오고, 배지+툴팁만 남습니다. 그래서 “발견 실패 = API/키 문제”로 오해하기 쉽고, 해결책(발견 끄기)이 다른 페이지에 묻힙니다. 이 이슈가 요구하는 건 발견 기능을 없애는 게 아니라, 실패 상태에서 의존 관계와 다음 행동을 Models 화면에 보여 달라는 것입니다.레지스트리 맥락도 짚어두면 좋습니다.
src/providers/registry.ts의google엔트리는 이미 정적 목록에gemini-3.8-flash등을 들고 있고(defaultModel은gemini-3.5-flash),liveModels: true를 명시하지는 않습니다. 그래도 관리/GUI 기본값이 “미설정 = ON”이라 AI Studio 키만 넣어도 라이브 목록을 치려다 실패 배지가 날 수 있습니다. Google Antigravity(google-antigravity)만 레지스트리에liveModels: true가 박혀 있습니다. 즉 Gemini API 수동 설정 UX는 “정적 카탈로그가 있는데도 발견이 기본으로 켜진 채 실패를 크게 보여 주는” 조합입니다. 2.49.0 tip(#4067)이나 #3719/#3379 슬라이스와는 무관하고, 범위는 GUI 카피·딥링크·(선택) google 기본값 정도면 됩니다.라인 - 이게 무슨 문제다
경로
src/server/management/provider-routes.ts(liveModels: p.liveModels !== false) - 미설정이면 발견 ON. Gemini 수동 설정에서도 라이브 동기화를 먼저 시도한다.
경로gui/src/components/provider-workspace/ProviderSettings.tsx(pws.liveModels토글) - 끄는 스위치는 Settings에만 있다. Models 실패 UI와 화면이 갈라진다.
경로gui/src/pages/Models.tsx(discoveryFailed 배지) - 실패 시 “发现失败”만 보이고, 발견 끄기/설정 이동 안내가 없다(비어 있을 때만 EmptyProviderHint 링크).
경로gui/src/pages/models-provider-hints.tsx- 빈 그룹에만 Providers 링크. 커스텀 모델이 있는데 발견만 실패한 작성자 케이스를 못 잡는다.
경로src/providers/registry.tsid: "google"- 정적 모델에gemini-3.8-flash가 이미 있다. 라이브 발견 기본 ON과 겹치면 “이미 있는 모델을 수동 추가했는데도 실패 배지”가 난다.
경로 관련 이슈 - #3630(주기적 카탈로그 갱신), #3666(무료 모델 필터)과 같은 catalog 축이지만 “실패 시 수동 모드로 가는 안내”는 이 이슈만의 UX다. 하나로 합치지 말 것.메인테이너의 판단이 필요한 지점
- Models 실패 배지에 “발견이 켜져 있음 → Settings에서 끄면 수동 모델만 사용” 문장+딥링크만 넣을지, Provider Settings와 Models를 한 워크플로로 묶을지.
google(AI Studio) 기본을liveModels: false(정적 목록 우선)로 바꿀지, 기본은 ON 유지하고 카피만 고칠지.- 발견 실패 시 수동/커스텀 행을 비활성처럼 보이게 하는 다른 경로가 있는지도 재현 확인이 필요한지(배지만인지, 실제 visibility까지인지).
너의 추천
작은 GUI UX PR을 받으세요. Models 제공자 헤더의 discovery-failed 배지 옆에 (또는 아래에)
pws.liveModels가 켜져 있다는 한 줄과 Providers Settings로 가는 링크를 넣으세요. EmptyProviderHint와 같은navigateHash("providers")면 충분합니다. 가능하면 실패 툴팁에 “수동 모델만 쓰려면 발견을 끄세요”를 중국어/영어 i18n에 추가하세요. google 기본값을 정적 우선으로 바꿀지는 별도 한 줄 결정이면 됩니다. types/config 무관. 중복 close 대상 아님.이 댓글은 grok-bot이 작성했습니다
- added a commit that references this issue
on Sep 9, 2026 Closed by #4158, merged to
devas8471ecccd8d8dd20c8b3d56858aa13ff8cc77ddf.The Models page no longer reports a bare "model sync failed". When discovery is the reason a provider has no models, the hint now names the dependency and tells the operator which control to turn off in provider settings to fall back to manually added or static models.
PRs here target
dev, so GitHub does not auto-close the linked issue; this is the manual close with the merge commit as evidence.- added a commit that references this issue
on Sep 10, 2026
Area
Catalog / models
What are you trying to accomplish?
I was trying to add a Gemini API provider and use gemini-3.8-flash as a custom model in OpenCodex.
The provider itself was configured correctly, including the Gemini API endpoint and API key. I also added the model manually in the model configuration.
What prevents this today?
The setup workflow is confusing because several related settings are distributed across different pages, while the dependency between them is not clearly communicated.
In my case, the provider had “Discover models from provider” enabled. However, I was adding the model manually rather than relying on provider-side model discovery.
This resulted in a “model sync failed” / “发现失败” state, but the UI did not clearly explain:
The relevant setting is located on the provider's Settings page, while the resulting model state is presented on a separate Models page. As a result, the problem appears to be an API/provider/model failure rather than a configuration or workflow issue.
I spent a considerable amount of time troubleshooting the API configuration before eventually discovering that disabling “Discover models from provider” fixed the problem.
The main issue is therefore not that the setting exists, but that the UI does not make the relationship between these settings and the resulting error state sufficiently clear.
What should OpenCodex do?
OpenCodex should make this workflow more discoverable and provide actionable diagnostics.
For example:
More generally, the UI should expose configuration dependencies rather than requiring users to discover them by trial and error.
Example usage or interface
A possible improvement would be an inline message such as:
Model discovery is enabled for this provider.
OpenCodex will attempt to discover models automatically. If you want to manage models manually, disable “Discover models from provider” in Provider Settings.
And if synchronization fails:
Model discovery failed.
Check the provider configuration or disable “Discover models from provider” if you want to use manually configured models.
[Open Provider Settings]
Alternatively, the Models page could display the dependency directly:
Model discovery: Enabled
Models are currently managed through provider discovery.
To use manually added models, disable model discovery in Provider Settings.
The important point is that the user should be able to understand what is wrong and where to fix it from the page where the problem is displayed.
Alternatives or workarounds
The workaround I eventually discovered was:
However, this workaround is difficult to discover because the relevant setting is on a different page and the model synchronization error does not point to it.
Additional context
This was particularly difficult to diagnose because the provider configuration itself appeared reasonable:
The model was successfully added to the model configuration, but its status still indicated that it was unavailable / disabled, while the provider displayed a “发现失败” (discovery failed) state.
Checks