CC Switch aggregation
Add working Orbis providers to aggregation, choose a default, refresh your client's model list and verify requests.
Once you have connected CC Switch to Orbis, use aggregation to select models from several providers in one client. For screenshots, installation and a two-provider exercise, see the illustrated aggregation guide.
1. Verify each provider first
- Use a CC Switch 4.x version that supports aggregation. This page covers Claude Code and Codex. Claude Code requires version
2.1.243or newer. - Aggregation uses the routing service on your machine. Keep CC Switch running while using it. Configure providers and aggregation lists separately for each client.
- Create a key for each Orbis route. Test each provider in ordinary mode first: check its URL, protocol, exact model ID and usage logs.
- Claude official subscriptions are currently unsupported in aggregation. A Codex official account can only be the default provider, not a regular aggregation member.
| Client | Orbis connection |
|---|---|
| Claude Code | Anthropic Messages; https://api.orbiorbi.com; for example, claude-haiku-5-5 |
| Codex | OpenAI Responses; https://api.orbiorbi.com/v1; for example, gpt-6.1-sol |
Use the protocol and models shown on the selected route's access page.
2. Add providers, then activate aggregation
- Select the corresponding client in CC Switch, then open the Aggregation tab.
- Edit the Orbis provider's Models list. Fetch and select the available models, or add exact supported model IDs manually if the list endpoint is unavailable. Both main and background models must be authorized by the key.
- Click Add in the Available list. Choose the default provider, then click Switch to Aggregation.
- Check the default provider and model count in the confirmation dialog, then confirm. The page should show Aggregation is active.
Saving a provider, adding it to the list and activating aggregation are separate steps. Viewing the tab or saving a model list does not activate aggregation.
The default provider handles requests without a provider prefix. For Claude Code, its first model (marked ★) also serves startup and background tasks. Check that this model is available to the key. Set another provider as default before removing the current default.
3. Refresh the client and verify requests
| Client | After changing the aggregation list or model configuration |
|---|---|
| Codex desktop app | Quit completely and reopen |
| Codex CLI | Use the notice to restart the Codex daemon, then reopen the CLI; this interrupts other running Codex tasks |
| Codex editor extension | Reopen the editor window |
| Claude Code | Reselect the model if prompted; the list normally updates immediately |
In the client's model picker, select a model by its provider label. Send a short message and check Usage logs. Select another entry and verify again. Each request uses that service's allowance. Do not construct ccs- model prefixes yourself.
Troubleshooting and recovery
| Symptom | Action |
|---|---|
| Only old models appear | Confirm the provider was added and aggregation activated, then reload the client as described above |
| Ordinary requests use the wrong service | Check the aggregation default provider, not just the last card you edited |
| Main conversation works but background tasks fail | Check that the key authorizes the background model |
| One provider fails | Manually select another tested provider; aggregation does not provide automatic failover |
| Cross-provider sub-agents cannot read their tasks | Keep Classic sub-agent tools in aggregation enabled; see the official manual for configuration overrides |
| Third-party requests also stop after official quota runs out | Codex may block sending before requests reach CC Switch. Return to Direct, turn off Keep official login for direct switches under CC Switch's Settings → App config → Codex, activate a third-party provider, fully restart Codex and start a new session |
| Leave aggregation | Click Back to direct, activate the original provider, reload the client and check its status |
The official-quota workaround temporarily leaves only the selected third-party provider available. After the quota resets, return to aggregation and restart Codex; CC Switch restores the official login it set aside.
Your Orbis key still determines the route. CC Switch aggregation does not let one key access multiple routes automatically. See the illustrated tutorial for model lists, default settings and recovery, and the official CC Switch aggregation manual for sub-agents, official-quota limits and version differences.