Skip to content

Latest commit

 

History

History
268 lines (219 loc) · 14.1 KB

MODELS.md

File metadata and controls

268 lines (219 loc) · 14.1 KB

Models

Default and fallback model assignments for every harness in this repo.

Source of truth

models.json maps a stable alias to a concrete model ID. Templates (*.tpl.*) reference the alias as an __UPPER_SNAKE__ placeholder; scripts/llm-update.sh sed-substitutes them into the generated configs.

make llm-update

Never hand-edit a generated config. Edit the .tpl.* file, regenerate, and commit both.

Aliases

Placeholder Model ID
__CLAUDE_OPUS__ claude-opus-5-5
__CLAUDE_SONNET__ claude-sonnet-5-5
__CLAUDE_HAIKU__ claude-haiku-5-5
__GPT__ gpt-6.1-sol
__GPT_ASTRA__ gpt-6-astra
__GPT_SOL__ gpt-6.1-sol
__GPT_LUNA__ gpt-6-luna
__GPT_IMAGE__ gpt-image-2
__GEMINI_FLASH__ gemini-3.8-flash
__DEEPSEEK_FLASH__ deepseek-v4.1-flash-1017
__DEEPSEEK_FLASH_UNCENSORED__ deepseek-v4.1-flash-uncensored
__GEMMA_LOCAL__ gemma3:4b
__MINIMAX__ minimax-m3
__KIMI__ kimi-k3
__GROK__ grok-4.6
__QWEN__ qwen3.6-plus
__QWEN_LOCAL__ qwen3.5-0.8b-optiq

This table is the complete set of keys in models.json. Every key also gets two derived forms: __<KEY>_PRETTY__ for the display name ("Deepseek V4.1 Flash") and __<KEY>_NONDOT__ for the dot-stripped ID, used in OpenRouter @preset/ names.

Provider-specific slugs remain separate even when they represent the same model family. __GEMINI_FLASH__ is the Gemini ID verified through CLIProxy, while Antigravity's native model ID stays directly in its provider-owned template.

Provider-specific overrides are declared in scripts/llm-update.sh rather than in models.json, because the upstream ID differs from the canonical one:

Placeholder Value Used by
__GPT_IMAGE_OPENROUTER__ openai/gpt-5.4-image-2 OpenRouter, aliased back to gpt-image-2
__GPT_LUNA_OPENROUTER__ openai/gpt-6-luna OpenRouter, aliased back to gpt-6-luna
__CLAUDE_HAIKU_OPENROUTER__ anthropic/claude-haiku-5.5 OpenRouter, aliased back to claude-haiku / claude-haiku-5-5
__DEEPSEEK_FLASH_OPENROUTER__ deepseek/deepseek-v4.1-flash OpenRouter, aliased back to deepseek-v4.1-flash-1017
__DEEPSEEK_FLASH_UNVERSIONED__ deepseek-v4.1-flash Ollama and NVIDIA upstream IDs
__DEEPSEEK_FLASH_0731__ deepseek-v4-flash-0731 Aliyun, aliased back to deepseek-v4.1-flash-1017
__DEEPSEEK_FLASH_ZEN__ deepseek-v4-flash OpenCode Zen, aliased back to deepseek-v4.1-flash-1017

Free campaign models

models.free.json holds time-limited free models served by the CLIProxy campaign providers. Key foo fills __FREE_FOO__; there are no _PRETTY or _NONDOT forms. union is the upstream ID behind the reserved free alias on openrouter-campaign. The rest are exposed under their own IDs on the keyless opencode-campaign. A foo-<provider> key holds the upstream ID another provider serves under the foo alias: minimax-flash routes through OpenRouter (minimax-flash-openrouter) and Ollama Cloud (minimax-flash-ollama).

When a campaign rotates its model, change the value and run make llm-update. When a campaign ends, delete the key and its models: entry in config.tpl.yaml.

CLIProxy allowlist

CLIProxy serves the Codex OAuth models (__GPT_LUNA__, __GPT_SOL__, __GPT_ASTRA__, gpt-5.6-terra, gpt-5.5), the DeepSeek compatibility aliases (deepseek-v4.1-flash-1017 and deepseek-v4.1-flash-uncensored), free, and the models.free.json models. Models that Codex OAuth cannot serve are removed with oauth-excluded-models, which matches upstream IDs and has no negation, so a new upstream Codex model is served until it is added there.

The shared fallback chain

Harnesses that support runtime fallback use one chain, in this order:

deepseek-v4.1-flash-1017  (primary)
  -> free           (OpenRouter free router, last resort)

Rules:

  • deepseek-v4.1-flash-1017 is the only DeepSeek model on any automatic path.
  • Every hop resolves through CLIProxy, so provider-level rotation (Surplus -> Ollama -> Aliyun -> Verboo/CommandCode -> NVIDIA -> OpenRouter -> OpenCode) already happens inside a single hop. Do not add a hop that repeats the primary model.
  • Keep the chain model-diverse. Each hop should be a different vendor family so a vendor-wide outage cannot exhaust the chain.

Per-harness assignments

Fallback-capable

Harness Default Fallback chain Config
OpenCode shunkakinoki/deepseek-v4.1-flash-1017 shared chain, shunkakinoki/ prefix opencode-fallback.tpl.jsonc
OpenClaw cliproxy/deepseek-v4.1-flash-1017 shared chain, cliproxy/ prefix openclaw.tpl.json
Hermes cliproxy/deepseek-v4.1-flash-1017 shared chain via fallback_providers config.tpl.yaml
OMP cliproxyapi/deepseek-v4.1-flash-1017 shared chain, cliproxyapi/ prefix config.tpl.yml

OpenCode fallback is driven by the opencode-runtime-fallback@0.2.3 plugin:

Setting Value
retry_on_errors 401, 404, 429, 500, 502, 503, 504, 524
retryable_error_patterns unknown provider for model, Model is unavailable
max_fallback_attempts 5
cooldown_seconds 60
timeout_seconds 30

OpenClaw and Hermes have no equivalent error-pattern matcher, so they hard-fail on the unknown provider for model <prefixed-name> 400 that OpenCode absorbs. OMP uses native retry.fallbackChains instead of a plugin.

Hermes also runs a Mixture-of-Agents preset: reference models deepseek-v4.1-flash-1017 + minimax-m3, aggregator deepseek-v4.1-flash-1017.

No fallback chain

Harness Role Model Config
OpenCode small_model shunkakinoki/deepseek-v4.1-flash-1017 opencode.tpl.jsonc
OpenCode code-reviewer agent shunkakinoki/deepseek-v4.1-flash-1017 opencode.tpl.jsonc
OMP smol, commit, task cliproxyapi/free config.tpl.yml
OMP slow, vision, plan cliproxyapi/deepseek-v4.1-flash-1017
Codex default gpt-6.1-sol config.tpl.toml
Codex subagents gpt-6-luna
Codex qwen-local profile qwen3.5-0.8b-optiq (LM Studio)
Claude Code subagents, opus alias claude-opus-5-5 settings.tpl.json
Claude Code sonnet, haiku aliases claude-sonnet-5-5
Antigravity default gemini-3.8-flash (native Antigravity provider) settings.tpl.json
Pi defaultModel free (provider cliproxyapi) settings.tpl.json
Factory (droid) session default deepseek-v4-flash-0731 (Droid Core) settings.tpl.json
Factory (droid) custom models custom:deepseek-v4.1-flash-1017-0, custom:free-1 via https://cliproxy.shunkakinoki.com/v1 settings.tpl.json
aichat default cliproxy:deepseek-v4.1-flash-1017 config.tpl.yaml
DSH web default deepseek-v4.1-flash-1017 via https://cliproxy.shunkakinoki.com/v1 (native DeepSeek adapter) settings.tpl.yaml
Reasonix default_model cliproxy-deepseek-flash -> deepseek-v4.1-flash-1017 via https://cliproxy.shunkakinoki.com/v1 config.tpl.toml
llm default deepseek-v4.1-flash-1017 default_model.tpl.txt
Handy transcript post-process @preset/deepseek-v4.1-flash-1017 (OpenRouter) settings_store.tpl.json

OMP selects only cliproxyapi/*. Subagent overrides use deepseek-v4.1-flash-1017 for the hard-task roles and free for the lightweight roles. The registry in models.tpl.yml lists the CLIProxy aliases and discovers the rest from remote /v1/models. OMP fallback uses the shared chain (deepseek-v4.1-flash-1017 -> free).

Fish shortcuts

The l suffix means local (LM Studio), c means CLIProxyAPI, h means headless.

Function Model
ocxe, ocxeh cliproxyapi/deepseek-v4.1-flash-1017
ocxel, ocxelh lmstudio/qwen3.5-0.8b-optiq
coxe, coxeh gpt-6.1-sol
coxec, coxech gpt-6-luna (--profile cliproxy)
coxel, coxelh qwen3.5-0.8b-optiq (--oss --local-provider lmstudio)
pixe, pixeh cliproxyapi/deepseek-v4.1-flash
pixel, pixelh lmstudio/qwen3.5-0.8b-optiq

CLIProxy routing

Three provider prefixes appear above. All three are CLIProxy. Each harness names its own, so the prefix alone does not tell you remote vs local. cliproxyapi/ in particular means different endpoints in different harnesses.

Prefix Harness Endpoint
shunkakinoki/ OpenCode https://cliproxy.shunkakinoki.com/v1 (remote)
cliproxy/ OpenClaw, Hermes https://cliproxy.shunkakinoki.com/v1 (remote)
cliproxyapi/ OpenCode http://localhost:8317/v1 (local)
cliproxyapi/ OMP https://cliproxy.shunkakinoki.com/v1 (remote)
cliproxyapi/ Pi https://cliproxy.shunkakinoki.com/v1 (remote)

Every one of them resolves through config.tpl.yaml.

routing.strategy is round-robin: within the highest ready priority tier, credentials rotate one at a time. priority still decides which tier is eligible at all, so a request only reaches a lower tier once every credential above it is cooling down or unavailable.

Provider Priority DeepSeek models served
morph-deepseek 304 morph-dsv41flash-1017 aliased to deepseek-v4.1-flash-1017
surplus-deepseek 301 deepseek-v4.1-flash-1017 aliased to deepseek-v4.1-flash-1017
ollama-cloud 300 deepseek-v4.1-flash aliased to deepseek-v4.1-flash-1017
aliyun 200 deepseek-v4-flash-0731 aliased to deepseek-v4.1-flash-1017
verboo, commandcode 150 deepseek-v4-flash-0731 aliased to deepseek-v4.1-flash-1017
nvidia 120 deepseek-ai/deepseek-v4.1-flash aliased to deepseek-v4.1-flash-1017
openrouter 100 deepseek/deepseek-v4.1-flash aliased to deepseek-v4.1-flash-1017
opencode 90 deepseek-v4-flash aliased to deepseek-v4.1-flash-1017
surplus 150 deepseek-v4.1-flash-uncensored served under its own alias
So deepseek-v4.1-flash-1017 requests use Morph's morph-dsv41flash-1017 at
priority 304 first; Surplus revision 1017 at priority 301 is the next eligible
tier, and lower tiers only serve once the tier above them is unavailable. The
legacy deepseek-v4.1-flash and deepseek-v4-flash aliases use the same chain.
deepseek-v4.1-flash-uncensored is served only by Surplus, its
sole upstream.

Provider failure classification

CLIProxy retries a provider when it reports a rate limit or transient upstream failure. Some OpenAI-compatible providers report temporary model capacity as HTTP 400, so the DeepSeek providers carry a narrow request-scoped-errors rule for the exact Model is unavailable response. The rule uses continue-and-cooldown: the current provider is cooled down and the same model is tried at the next eligible priority. Other HTTP 400 responses remain terminal client errors.

Provider Known model-unavailable response 429 behavior Failover action
morph-deepseek HTTP 400, Model is unavailable provider rate limit continue and cool down
surplus-deepseek HTTP 400, Model is unavailable provider rate limit continue and cool down
nvidia HTTP 400, Model is unavailable provider rate limit continue and cool down
opencode HTTP 400, Upstream request failed: Model is unavailable provider rate limit continue and cool down
ollama-cloud HTTP 400, Model is unavailable provider rate limit continue and cool down
aliyun HTTP 400, Model is unavailable provider rate limit continue and cool down
verboo HTTP 400, Model is unavailable provider rate limit continue and cool down
commandcode HTTP 400, Model is unavailable provider rate limit continue and cool down
openrouter HTTP 400, Model is unavailable provider rate limit continue and cool down

The 400 entries are configuration contracts for observed or compatible provider responses; refresh them when a provider trace shows a different body. Do not add a blanket HTTP 400 retry rule.

Changing a model

  1. To swap a model version everywhere: edit models.json, run make llm-update, commit the template and generated files together.
  2. To change a default or a fallback hop for one harness: edit that harness's .tpl.* file, run make llm-update.
  3. Update the matching assertions in spec/llm_update_spec.sh, spec/openclaw_hydrate_spec.sh, spec/hermes_hydrate_spec.sh, and spec/cliproxyapi_spec.sh, then run shellspec.

Codex CLIProxy profiles

Codex loads named profile files from ~/.codex/<name>.config.toml. Activation installs the files from config/codex/profiles/; make llm-update hydrates their model IDs from models.json.

Profile Model key Command
cliproxy gpt-luna coxec or codex --profile cliproxy
cliproxy-astra gpt-astra codex --profile cliproxy-astra
cliproxy-sol gpt-sol codex --profile cliproxy-sol
cliproxy-luna gpt-luna codex --profile cliproxy-luna

The default cliproxy profile remains Luna for fleet consumers. Every profile uses the existing cliproxyapi provider and CLIPROXY_API_KEY; none consumes a host's native Codex login. qwen-local also uses a named profile file.