Repository navigation
Document that --model/-m pins and disables plugin fallback #47040
Description
Summary
--model / -m pins the session model. Plugin-configured models[] / runtime fallback never runs for that invocation. Reasonable, but undocumented as disables failover, so users who set a backup gateway never see it when they also pass -m.
Repro
- Plugin fallback chain: gateway-a/model then gateway-b/model.
- opencode run -m gateway-a/model --agent sisyphus ping while gateway-a returns 429.
Actual
No hop to gateway-b.
Expected
Document that -m pins and skips fallback. Optionally warn once when -m is combined with a plugin that advertises fallback models.
Suggested fix
Docs plus a single warning. Do not change pin semantics unless maintainers want an opt-in --allow-fallback.
Activity
fix(cli): fail closed on unknown --agent after remapping
opencodejr commentedon Oct 28, 2026
Thanks for the clear write-up, @RaviTharuma!
The report doesn't give a version, but the setup (the
sisyphusagent and a plugin-definedmodels[]fallback chain) looks like OpenCode v1 (versions 0.x/1.x, npmopencode-ai) with a third-party plugin. v1 now only gets fixes for critical bugs such as data loss, security problems or crashes with no workaround. Docs changes and new warnings like this one are unlikely to be made there. Also, the fallback chain is the plugin's own feature, so whether-mskips it is mostly up to the plugin. Its maintainers may be the best people to document it or add the warning.We'd encourage trying OpenCode v2 (npm
@opencode/cli). Core v2 doesn't fall back to another model after retries run out. That's being discussed here:If you're actually on v2 (please share
opencode --version), or you think this is critical, reply here and we'll take another look.opencodejr commentedon Oct 29, 2026
We haven't heard back, so I'm closing this as not planned. The setup (the
sisyphusagent with a plugin-definedmodels[]fallback chain) points to OpenCode v1, which only gets critical fixes. The fallback behaviour also belongs to the plugin, so its maintainers are best placed to document how-minteracts with it.If this happens on OpenCode v2 (
@opencode/cli), please reply with youropencode --versionand we'll reopen it. For built-in model fallback in v2, see #48991.