CC-Switch with AIXHUB

CC-Switch manages desktop client configuration and also offers an optional local proxy. This guide creates direct AIXHUB profiles using native Anthropic Messages and OpenAI Responses, so Needs Local Routing stays off and CC-Switch is not placed in the request path. A switch is successful only when the target application loads the expected values and AIXHUB records the matching request.

What you will accomplish

You will:

1. Install the canonical farion1231/cc-switch release for your platform.
2. Back up the target files and record the previously active profile before switching.
3. Create separate AIXHUB profiles for Claude Code and Codex, each with its own dedicated key.
4. Verify settings.json, config.toml, and whether auth.json was preserved or changed by the selected Codex compatibility setting instead of trusting an active badge alone.
5. Run one read-only or tool-free request and match its time, model, and successful status in AIXHUB Usage.
6. Restore only the fields owned by this change while preserving unrelated providers, official sign-in data, and later settings.

CC-Switch releases can rename controls or reorganize target tabs. This guide does not invent a fixed menu label or an internal database schema. It treats the target application's files and behavior as the observable contract.

Supported platforms

Use only packages published by the canonical project on its official Releases page:

• Windows: Windows 10 or later; official x64 and ARM64 MSI/portable artifacts are published.
• macOS: macOS 12 or later; use the signed and notarized official macOS artifact.
• Linux: Ubuntu 22.04+, Debian 11+, Fedora 34+, or another compatible mainstream distribution; official x86_64 and ARM64 AppImage, DEB, and RPM artifacts are published.

If the official release does not provide a compatible artifact, do not substitute a similarly named project or an unofficial download. The exact asset names and installation prompts can change between releases.

This guide covers two CC-Switch targets:

Some CC-Switch versions may display other targets. Their presence does not prove direct AIXHUB compatibility. In particular, do not enter an AIXHUB key into a Gemini or official-account profile unless AIXHUB and that target document a compatible custom endpoint.

Install or open the app

1. Open the canonical CC-Switch Releases page. The platform assets and requirements above were checked against the current official release; always choose the newest compatible artifact rather than copying an old direct URL.
2. Select the release asset for the current operating system and architecture, then follow the operating system's normal installation or launch flow.
3. Record the release tag shown on the download page. If the installed build exposes an About or version view, confirm it matches; the location of that view can vary.
4. Fully close Claude Code, Codex desktop, Codex CLI, and editor integrations before CC-Switch writes their shared files.

Do not import an unreviewed profile exported by someone else. A profile or backup can contain API keys, target paths, and provider settings even when the CC-Switch window hides the secret.

Configuration values

Create two App-specific Provider profiles rather than one Universal Provider. The two occurrences of sk-your-key below are placeholders for different dedicated AIXHUB keys; never reuse one real key for both targets.

Copy the exact model ID from Model routes. Claude Code uses the root Base URL without /v1; Codex uses exactly one /v1. A Claude profile and a Codex profile are not interchangeable.

In the current upstream flow, select the target app, click the top-right +, choose App-specific Provider, and add a Custom provider. Provider names and advanced-field placement can still change, so map by meaning and verify the generated files below. If the installed release cannot represent every required value, cancel the switch and use the dedicated Claude Code or Codex CLI guide instead.

Configure AIXHUB

Protect the original state

Before creating or activating a profile:

1. Fully close both target applications and any editor integrations that use them.
2. Copy every existing target file to a uniquely named, timestamped backup outside any repository. Do not overwrite an older backup.
3. Record whether each file was absent and record the previously active CC-Switch profile for each target.
4. Keep a protected field-level record of the values listed below. Store exact secret values only in the protected file backup, not in notes or screenshots.

Current releases store CC-Switch data under ~/.cc-switch/, use cc-switch.db as the provider source of truth, and keep rotating database backups under ~/.cc-switch/backups/. Settings -> Advanced -> Data Management also provides export/import, and import overwrites the database. These are additional recovery artifacts only; explicit target-file copies remain the recovery source of truth, and every database backup or export must be treated as a secret.

Create the Claude Code profile

Select Claude Code, click the top-right +, choose App-specific Provider -> Custom, and enter the Claude column from the values table. Keep the API format on Anthropic Messages and local routing off. Review the JSON preview, then click Add. Do not click Enable until the backup and preview checks above are complete.

After the switch, the user-level Claude settings must contain or preserve this complete env object:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aixhub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key",
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_MODEL": "panel-model-id"
  }
}

The real file may have unrelated top-level properties. CC-Switch must merge the shown fields without deleting those properties. Both credential variables use the same Claude-specific AIXHUB key; the Codex profile must use a different real key.

Create the Codex profile

Select Codex, click the top-right +, choose App-specific Provider -> Custom, and enter the Codex column from the values table. Keep Needs Local Routing off because AIXHUB exposes native Responses. Review the generated configuration, then click Add. Do not click Enable until you have selected and verified the credential projection mode below. The current CC-Switch custom-provider template uses the provider ID custom; its live config.toml must contain:

model_provider = "custom"
model = "panel-model-id"

[model_providers.custom]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true

The two top-level keys must remain before any TOML table. Preserve unrelated providers and settings, and keep only one active [model_providers.custom] table for this profile.

Current releases store the profile's API key in the CC-Switch database. When the installed build's preserve Codex official authentication on switch compatibility setting is enabled, switching a third-party provider leaves the user's ChatGPT login cache in auth.json untouched and projects the key into the active provider table:

[model_providers.custom]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "sk-your-key"

This mode is recommended when auth.json already contains an official sign-in. Verify the field exists without printing its value. Do not add the token manually after a successful switch; CC-Switch owns the projection and backfill.

If that compatibility setting is deliberately disabled, the build can instead write the stored provider authentication to auth.json in this shape:

{
  "OPENAI_API_KEY": "sk-your-key"
}

Choose one observed mode; never require both. Before switching, record whether auth.json contains official login material. After switching, confirm either that it remained byte-for-byte untouched while the provider-scoped bearer token appeared, or that the explicitly selected replacement mode wrote the documented API-key shape. If neither outcome matches the preview, restore immediately.

Activate one target profile

Select the provider card and click Enable, or choose the provider from the target submenu in the system tray. This is state-changing: it writes the selected target's live configuration. Confirm the target application and profile name before accepting it.

An active badge is only CC-Switch's local state. Before opening the target client, inspect the target files without printing the key and confirm the expected Base URL, model, protocol, and selected credential projection mode. If the file preview and actual file disagree, stop and restore instead of repeatedly switching.

First run

Test one target at a time, from a small disposable directory.

Claude Code

1. Activate AIXHUB - Claude Code and confirm settings.json contains the expected root URL and model.
2. Fully restart Claude Code.
3. Start claude, confirm panel-model-id when the client displays a model, and send this bounded request:

Do not call tools, run commands, or change any file. Reply with OK only.

Do not approve file writes, state-changing commands, or access outside the test directory.

Codex

1. Close Claude Code, activate AIXHUB - Codex, and confirm model_provider = "custom" plus the expected provider table. Verify the selected credential mode without displaying the bearer token or API key, and confirm whether auth.json was meant to remain untouched.
2. Fully restart the intended Codex surface.
3. Start codex or open Codex desktop, confirm panel-model-id when visible, and send the same read-only request.

Switching a profile while the target application is running can leave the current process on its old provider. Always restart before judging the result.

Verification

A successful target request should contain this output:

OK

Verify all three layers:

1. CC-Switch state: The intended target and AIXHUB profile are marked active.
2. Target state: The real target files contain the expected values, and the restarted client shows the intended model when it exposes that information.
3. AIXHUB record: In AIXHUB Usage, match the request time, panel-model-id, and successful status. Compare the protocol only when Usage actually displays it.

A response alone does not prove the route. Repeat this verification separately for Claude Code and Codex because they use different keys, Base URLs, protocols, and files.

Troubleshooting

The controls or target names look different

Record the installed release tag and compare it with the canonical release notes. CC-Switch versions can reorganize targets and rename controls. Do not import a guessed internal JSON shape or follow a menu path from another build. Navigate by target and field meaning, then verify the actual target files.

CC-Switch says active but the client uses the old provider

Fully close and restart the target. Confirm that CC-Switch changed the correct operating-system user and target file. For Claude Code, remove or align stale temporary ANTHROPIC_* environment variables. For Codex, inspect CODEX_HOME, the test project, and trusted parent directories for .codex/config.toml overrides.

Claude Code returns 401 or still uses the official route

Confirm ANTHROPIC_BASE_URL is exactly https://api.aixhub.org without /v1, both credential variables contain the dedicated Claude key, and ANTHROPIC_MODEL contains the exact model ID. Restart Claude Code after correcting the profile.

Codex opens an official login or returns 401

Confirm model_provider = "custom", requires_openai_auth = true, and the AIXHUB Base URL. In preserve-official-auth mode, verify that the active provider has a non-empty experimental_bearer_token without printing it and that auth.json stayed unchanged. In replacement mode, verify the dedicated OPENAI_API_KEY was written exactly as previewed. Do not use an official ChatGPT login as the AIXHUB credential. Restart every Codex surface because desktop and CLI share the live configuration.

A request returns 404 or the API version is doubled

Check the selected target. Claude uses https://api.aixhub.org; Codex uses https://api.aixhub.org/v1. Never append /v1 to the Claude profile, never remove it from the Codex provider, and never place /v1/responses in a Base URL field.

The model is not found

Copy the complete model ID again from Model routes. Keep Claude's ANTHROPIC_MODEL, Codex's top-level model, and the profile's model field synchronized. Do not copy the AIXHUB provider name into the model ID.

Switching removed unrelated settings

Stop both CC-Switch and the target client. Do not switch again. Compare the current file with the protected backup, restore only from the exact artifact for this operation, and preserve unrelated fields added after the backup. Treat this as a configuration-write failure rather than an API error.

For 403, 429, 502, or 503 responses, continue with the error code reference.

Upgrade and restore

Before upgrading CC-Switch, repeat the target-file backups and record the active profiles. Install updates only from the canonical Releases page, retain the previous release tag until verification is complete, and recheck generated files after the first switch on a new version.

To restore:

1. Fully close CC-Switch, Claude Code, Codex desktop, Codex CLI, and related editor integrations.
2. Reactivate the exact previous profile only when it is known and its preview matches the protected original record. Otherwise restore fields manually from the exact target-file backup.
3. For Claude Code, restore the complete original env object. Remove an AIXHUB env field only when its recorded original state was absent and its current value still belongs to this operation. Preserve unrelated top-level and later-added properties.
4. For Codex, restore the original model_provider, model, complete provider table, and provider-scoped bearer-token ownership. Restore auth.json only when the switch actually changed it; otherwise leave the preserved official sign-in cache untouched. If a field's origin is unknown, stop rather than deleting it.
5. Delete an AIXHUB profile from CC-Switch only after switching away from it and only when the protected record confirms that profile did not exist before this guide.
6. Validate the restored JSON and TOML, restart each target separately, and verify the restored provider before allowing tools or writes.
7. Revoke the two dedicated AIXHUB keys only after no restored profile or target still uses them.

If a target file was originally absent, delete the current file only when it still exactly matches the minimal configuration created by this guide and contains no later state. Otherwise keep the file and apply the field-level rules above.

Security

• Use a different dedicated AIXHUB key for each CC-Switch target profile. This isolates rotation, revocation, and Usage investigation.
• Treat CC-Switch's local data, exported profiles, target-file backups, and screenshots as secrets; any of them may contain credentials.
• Keep backups outside repositories and cloud-synced folders unless an approved encrypted secret-storage policy covers them.
• Never print a key, paste it into a prompt, commit it, or include it in release reports, screenshots, diagnostics, and support logs.
• Review the target, Base URL, model, and generated-file preview before every switch. A profile switch changes state even if no API request follows.
• Restrict target files and backups to the current operating-system user. On shared machines, prefer an operating-system secret store when the installed CC-Switch release supports one.
• Rotate a key immediately after exposure, update only the matching target profile, and repeat the read-only verification.

Official sources

• CC-Switch canonical repository
• CC-Switch official releases
• CC-Switch provider manual
• CC-Switch configuration files
• Claude Code settings
• Codex configuration reference

Last verified: 2026-07-14