Agent Fallback Models

Short answer: there's no built-in "auto-failover to a backup subscription" in Paperclip itself yet, but you can get most of the way there today with a combination of adapter config + a thin shim. A few angles depending on what "quota" means in your case:

1. Same provider, multiple API keys (e.g. two Anthropic / OpenAI accounts). The cleanest path is a local proxy that load-balances across keys and rotates on 429/quota errors — [LiteLLM Proxy](https://docs.litellm.ai/docs/proxy/loadbalancing) is the one most people here run. You point one Paperclip agent at the proxy's base URL via the adapter's env block (OPENAIBASEURL / ANTHROPICBASEURL, depending on the CLI), and the proxy handles the key rotation transparently. The agent never knows it switched.

2. Cross-provider fallback (Claude → Codex → Hermes, etc.). Paperclip's adapter is set per agent, not per request, so true mid-run failover across adapters isn't a thing today — once a heartbeat is in flight on claudelocal, it stays there. What you can do:

Run duplicate agents on different adapters, give them the same role spec, and let the CEO route around the one that's stuck. Crude, but it works. Wrap the CLI — point the adapter's command at a small script that tries the primary CLI, catches the quota error, and re-execs the secondary CLI with the same prompt. Because Paperclip just spawns whatever binary you set in command, the adapter doesn't care that it's actually a fallback wrapper underneath. This is the most reliable single-agent pattern I've seen. For OpenRouter-style routing, point the adapter at OpenRouter's endpoint and let it fall back across model providers.

3. "Quota" = monthly subscription cap on Claude/Codex CLIs. Trickier, because those CLIs auth against a single account at a time. The wrapper-script pattern above is the workaround — have it claude login --account A vs --account B based on which one still has budget, or swap ANTHROPICAPIKEY between two pay-as-you-go keys.

Worth flagging the use case in the Ideas (/categories/ideas) category too — first-party "adapter chain with fallback" is a reasonable feature ask and I haven't seen it filed yet. If you share which providers/CLIs you're juggling I can sketch a more concrete wrapper for your setup.

Yeah, sounds good, thanks!

How we did it: Manifest as single-endpoint router

We solved this with Manifest.build — an OpenAI-compatible gateway that auto-routes per request across providers. All 59 of our agents use one model string: \ XXXX (unable to post links at the moment but when given ability to I will). Manifest picks the live backend (we've seen MiniMax-M2.7, Codex variants, others) based on availability and cost. When one provider rate-limits,\ the next request lands on a different one transparently.

Setup in Paperclip: add Manifest as an openai-compatible provider in opencode.json with baseURL: XXXX (unable to post links at the moment but when given ability to I will) and apiKey: {env:MANIFESTAPIKEY}. Flip agent\ adaptertype to opencodelocal and model to manifest/<anything>. Done.

Pros

Zero adapter code — no failover logic to maintain Single API key, single bill, usage dashboard across providers Per-request routing means no "warmup" delay on failover Works inside opencode's existing provider system

Cons

Third-party dependency in the hot path — Manifest down = all agents down You don't choose which provider serves each call (good for cost, bad if you need deterministic model behavior) Single key = single quota point. Ironically replaces "N quotas" with "1 quota with N upstreams" opencode's model-discovery CLI hits /v1/models on every boot — Manifest doesn't implement it, so you need a small adapter patch to skip discovery for manifest/\ model strings\ or it times out (20s) No native concept of "use my Anthropic subscription first, then fall back" — Manifest's router decides

The other approach (if you want subscription-priority failover): keep multiple adapters configured per agent and write a wrapper that catches quota errors and retries on the\ next adapter. More code, more control. Probably belongs as a first-class Paperclip feature.

Would folks here use a built-in "fallback chain" config on agents — e.g., models: \[claudelocal, openrouter/sonnet, manifest/gpt-4o-mini\] with auto-retry on quota errors? If\ yes, +1 below and we'll consider upstreaming.

Would absolutely be helpful! Do upstream sir!