Feature: provider and model aliases — short names editable via pencil icon, CLI space, built-in default alias set

Area

Multiple areas

What are you trying to accomplish?

Short, user-chosen names (aliases) for providers and models, editable from the dashboard with a pencil icon next to each provider and model name, plus a matching CLI command space. Routed slugs today look like google-antigravity/gemini-3-pro-preview-11-2025 or openrouter/anthropic-claude-opus-4.6; users type these into Codex's model picker, /model, CLI flags, and combo targets. A short alias (agy/opus) removes friction on every one of those surfaces.

This was also raised by external user feedback on X (@terryaidev): "Probably add customized model name, since some of the model names can be very long and not good for user experience."

On top of user-set aliases, OpenCodex should ship a built-in default alias set for famous models (e.g. claude-opus-5* → opus, gemini-3-pro* → g3p), selectable per provider and per model scope, and applicable across all providers.

What prevents this today?

OcxCustomModel.displayName (src/types/config.ts:190) and combo displayName (src/types/config.ts:626) exist but are display-only; they never resolve at request time.
Combo aliases are the only resolvable aliases today (comboPublicModelId, src/combos/types.ts:76; resolved in routeModelInternal, src/router.ts:627-636). There is no equivalent for providers or individual models.
Live-catalog providers (liveModels: true) have model ids that never appear in static config, so there is no config row to hang a name on.

What should OpenCodex do?

Full design (config schema, request-time resolution order, collision rules, catalog exposure, management API, CLI, GUI, edge cases): devlog/_plan/260824_model_ux_aliases_and_defaults/010_aliases.md. Summary:

Config schema: providers.<name>.alias?: string (provider alias, id-shaped, validated against provider names/reserved namespaces), providers.<name>.modelAliases?: Record<nativeModelId, string> (survives live-catalog refresh because it is keyed by id, not config rows), providers.<name>.defaultAliases?: boolean + top-level defaultModelAliases?: boolean (built-in alias set opt-in, per provider or global; per-provider wins).
Built-in default alias set: curated pattern list in src/providers/default-aliases.ts (/^claude-opus-5/ → opus, etc.), matched against the full id and the segment after the last / so aggregator ids match too. User aliases always win over built-ins. Ambiguity (two models on one provider match the same rule) deterministically disables that built-in for that provider instead of guessing.
Request-time resolution: two hook points in routeModelInternal — qualified head/tail aliases extend the explicit provider-namespace step (below combo aliases, so combo names keep their meaning), while bare model aliases resolve late, after all existing bare steps and just ahead of the defaultProvider fallback. agy/opus resolves head as provider name-or-alias and tail as model id-or-alias in one pass. Bare aliases resolve only when globally unique; ambiguity is a deterministic error listing the qualified candidates. Case-insensitive matching. Upstream always receives the native id; logs record the native slug plus requestedAlias.
Catalog exposure: alias is an additional resolvable id; canonical slugs remain the row ids everywhere (selectedModels/disabledModels/usage untouched). Display uses the alias via the existing display_name path (src/codex/catalog/effort.ts:118-124).
Management API: PUT /api/providers/:name/alias, PUT /api/providers/:name/model-aliases (partial update, 409 with conflict detail), PUT /api/default-aliases, GET /api/aliases (effective view incl. source user|builtin and ambiguous built-ins).
CLI: new top-level space ocx alias list | set <provider>[/<modelId>] <alias> | rm <provider>[/<modelId>] | defaults on|off [--provider <name>].
GUI: pencil icon next to provider header and each model row (inline edit, inline 409 conflicts); "Use default aliases" toggle per provider + global toggle in the Models toolbar; bulk alias table view.

Example usage or interface

ocx alias set google-antigravity agy
ocx alias set openrouter/anthropic/claude-opus-4.6 opus
ocx alias defaults on                       # built-in alias set, all providers
ocx alias list
# KIND      TARGET                                        ALIAS   SOURCE
# provider  google-antigravity                            agy     user
# model     openrouter/anthropic/claude-opus-4.6          opus    user
# model     claude/claude-sonnet-5-20260203               sonnet  builtin

Then in Codex: /model agy/opus routes to google-antigravity + the aliased model; the picker shows agy/opus as the display name.

Alternatives or workarounds

Custom models with displayName — display-only, does not shorten what users must type, and cannot cover live-catalog models.
Combos as pseudo-aliases — heavyweight (one combo per model), pollutes the combo namespace, and cannot alias a provider.

Additional context

Design doc: devlog/_plan/260824_model_ux_aliases_and_defaults/010_aliases.md. Related: default preset issue and new-models-off issue filed alongside this one (all three compose; see doc cross-references).

Checks

I searched existing issues and documentation.
This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
I removed secrets and personal data.

리뷰 · 우선순위 48 / 80

설명: 이 이슈는 제공자와 모델에 짧은 별칭을 붙이자는 것이다. 대시보드 이름 옆에 연필로 고치고, 같은 일을 명령줄에서도 하게 한다. 지금은 라우팅 슬러그가 google-antigravity/gemini-3-pro-preview-11-2025 처럼 길다. 사용자는 코덱스 피커와 /model 과 콤보 목표에 그 긴 이름을 넣는다. 짧은 별칭 agy/opus 가 그 마찰을 줄인다. 사용자 별칭 위에 유명한 모델의 기본 별칭 묶음도 넣자고 한다. 지난 시간 2463 조사는 없는 번호였다. 이번 시간에 열렸다. 지금 CURRENT dev HEAD 는 35a89903c 이다. 이번 시간에 origin/dev 는 그대로다. 새 머지는 없다. package.json 은 2.27.0 이다. src/config.ts 는 3238줄이다. src/runtime 폴더는 지금 HEAD 에 없다.

하려는 일은 이렇다. 설정에 제공자 별칭과 모델 별칭 칸을 만든다. 산 카탈로그 아이디는 설정 줄이 없어도 아이디로 별칭을 건다. 요청이 오면 콤보 별칭 다음, 명시 제공자 이름 칸에서 머리와 꼬리를 같이 푼다. 맨몸 별칭은 기존 맨몸 단계 뒤, 기본 제공자 바로 앞에서 푼다. 전역으로 유일할 때만 맨몸이 이긴다. 애매하면 후보를 나열하고 에러다. 업스트림에는 원래 아이디만 간다. 카탈로그 행 아이디는 그대로 두고, 별칭은 추가 풀림 이름이다. 표시는 기존 display_name 길을 쓴다.

지금 HEAD 를 열었다. src/types/config.ts 190줄 displayName 은 커스텀 모델 표시명이다. 요청 때 풀리지 않는다. 콤보 displayName 은 626줄이고 역시 표시다. src/codex/catalog/effort.ts 118줄도 표시만 바꾼다고 적혀 있다. 지금 요청 때 풀리는 별칭은 콤보뿐이다. src/combos/types.ts 76줄 comboPublicModelId 와 src/router.ts 627줄 tryPickComboModel 이다. 제공자 설정 타입에는 alias 칸이 없다. src/providers 폴더에 default-aliases.ts 가 없다. src/cli 에 alias.ts 가 없다. src/cli/registry.ts 168줄 ocx models 는 커스텀 모델과 허용 목록이다. ocx alias 명령 공간은 없다. 이슈가 가리키는 설계 문서 폴더 devlog/_plan/260824_model_ux_aliases_and_defaults 는 지금 origin/dev HEAD 에 없다. 본문만 있다.

라우팅 순서가 위험하다. 669줄 네이티브 패밀리는 맨몸 별칭보다 먼저다. gpt- 같은 별칭은 그 자리에선 영원히 안 이긴다. 별칭을 네이티브보다 앞에 두면 코덱스 패밀리를 가로챈다. 콤보 이름이 제공자 별칭과 같으면 콤보가 이긴다. 그 규칙을 시험으로 고정해야 한다. 2299 는 산 발견 모델의 표시 라벨 초안이다. 요청 때 별칭이 아니다. 닫지 말 것. 표시 길은 재사용하되 라우팅은 이 이슈만 다룬다. 2464 새 모델 끄기와 2465 최신 프리셋은 같이 설계됐다. 별칭은 요청 길을 바꾼다. 카탈로그 가시성과 한 기차에 섞지 말 것. 2462 허브 콘솔과도 섞지 말 것. 2210 과 1049 과 2221 을 이 이슈로 닫지 말 것.

사용자 길이로는 매일 긴 슬러그를 치는 마찰이라서 48. 지금 요청이 502 로 죽지는 않는다. 잘못된 별칭 충돌은 나중에 잘못된 업스트림으로 돈을 쓴다. 그래서 라우팅 시험을 빼면 안 된다. 카탈로그 팁은 Ox Alpha x-preview-f-free + deepseek-v4-flash-vision-exp. Cursor 정적 카탈로그는 opus-4-8-fast / opus-5-fast. 2334 CursorCredentialRouter 는 여전히 src/providers/cursor-pool.ts 모듈+테스트만 있고 어댑터에 연결되지 않았다. 2332 H2 는 discovery 전용. 2320 overflow + 2342 는 이미 dev. 2188 사이드카는 이미 dev. 2361 __omit__ 는 이미 HEAD 다. combo-stream-preflight.ts 는 지금 HEAD 에 있다. src/lib/bounded-body.ts 128줄 취소 없는 던짐과 2426 나가는 크기 가드는 그대로다. 2451 wait 허용 목록은 아직 하이픈이다. 이번 별칭은 그 구멍들이 아니다.

src/types/config.ts 라인 190 - displayName 은 표시만이다. 요청 때 풀리지 않는다
src/codex/catalog/effort.ts 라인 118 - display_name 은 피커 라벨만 바꾼다. 라우팅 슬러그는 안 바꾼다
src/combos/types.ts 라인 76 - 지금 풀리는 별칭은 콤보뿐이다
src/router.ts 라인 627 - 콤보 별칭이 먼저 이긴다. 그 아래가 제공자 이름 칸이다
src/router.ts 라인 669 - 네이티브 패밀리가 맨몸 별칭보다 먼저다
src/cli/registry.ts 라인 168 - ocx models 는 있다. ocx alias 명령은 없다
이슈 2299 - 표시 라벨 초안이다. 요청 때 별칭이 아니다. 닫지 말 것
설계 문서 폴더 - 지금 origin/dev HEAD 에 없다. 본문만 명세다

메인테이너의 판단이 필요한 지점

설계 문서를 같은 기차에 먼저 넣을지. 넣는 편이 맞다. 없는 경로를 가리킨 채 구현하지 말 것
별칭 기차와 카탈로그 가시성 기차를 나눌지. 나누는 편이 맞다. 별칭은 요청 길이다
네이티브 패밀리와 같은 맨몸 별칭을 거절할지. 거절하는 편이 맞다
2299 표시 라벨을 이 이슈로 닫을지. 닫지 말 것
콤보 이름과 제공자 별칭이 겹칠 때 콤보가 이기는지. 이슈 본문대로 콤보가 이긴다. 시험으로 고정할 것

너의 추천
이슈는 열어 둔다. 설계 문서를 origin/dev 에 먼저 넣는다. 요청 때 풀림과 충돌 시험만 좁게 본다. 표시 라벨은 2299 와 길을 나눈다. 2464 와 2465 와 한 기차에 섞지 말 것. 2210 과 1049 과 2221 과 2451 은 닫지 않는다. 호출 길을 넓히지 말 것. 라벨은 그대로 둔다. 프리뷰 배포가 아니다.

이 댓글은 grok-bot이 작성했습니다

devlog: model/provider UX design unit — aliases, new-models-off, defa…

feat(aliases): provider and model aliases across router, API, CLI and…

Closed on dev by #2610 (squash 05ced3caedf83f3f0030e290eecb5ae002f296fd).

Provider and model aliases ship across the router, management API, ocx alias, and the Models page pencil controls, with a built-in pattern set behind an opt-in toggle.

Aliases are a resolution and display layer, never a storage format: selectedModels, disabledModels, combos and usage rows keep canonical slugs, so an alias can be renamed or removed without touching persisted state. /v1/models annotates rows with alias_of rather than adding alias rows, so no existing client sees a row it does not recognise.

Resolution extends the ladder at two points, not one — qualified aliases below combo aliases, bare aliases immediately before the defaultProvider fallback. That ordering is what makes the collision rules sufficient: an alias can never shadow something that resolves earlier. The one deliberate behavior change (a bare id that today reaches the defaultProvider fallback resolving via alias) is tested in both directions, including that users with no aliases are unaffected.

Built-ins are patterns rather than ids, so snapshot suffixes do not stale them; when two models on one provider match the same rule the built-in is disabled for that provider rather than guessed.

GitHub only auto-closes on merges into main; PRs here target dev, so closing manually.

fix: repair three regressions from the #2463/#1478 landings (#2614)

Landed via #2610 at 05ced3c

fix(gui): translate the alias catalog keys and unbreak the locale par…

feat(oauth): activate multi-account 429 failover on account presence …

Merge from upstream (#8)

feat(aliases): provider and model aliases across router, API, CLI and…

fix: repair three regressions from the lidge-jun#2463/lidge-jun#1478 …

feat(oauth): activate multi-account 429 failover on account presence …

devlog: model/provider UX design unit — aliases, new-models-off, defa…

feat(aliases): provider and model aliases across router, API, CLI and…

fix: repair three regressions from the lidge-jun#2463/lidge-jun#1478 …

feat(oauth): activate multi-account 429 failover on account presence …

Navigation Menu

Repository navigation

Feature: provider and model aliases — short names editable via pencil icon, CLI space, built-in default alias set #2463

Area

What are you trying to accomplish?

What prevents this today?

What should OpenCodex do?

Example usage or interface

Alternatives or workarounds

Additional context

Checks

리뷰 · 우선순위 48 / 80

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Feature: provider and model aliases — short names editable via pencil icon, CLI space, built-in default alias set #2463

Description

Area

What are you trying to accomplish?

What prevents this today?

What should OpenCodex do?

Example usage or interface

Alternatives or workarounds

Additional context

Checks

Activity

lidge-jun commented on Aug 24, 2026

리뷰 · 우선순위 48 / 80

lidge-jun commented on Aug 25, 2026

lidge-jun commented on Aug 25, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions