Cc Switch

Manage API providers for Codex and compatible CLI tools with automatic mode detection, pre-switch connectivity tests, and endpoint URL updates.

eohmig@eohmig

Install

openclaw skills install @eohmig/cc-switch

CC Switch - Dual-Mode Provider Management

A provider management skill that works in two modes automatically:

Mode	When Active	Data Storage
cc-switch mode	cc-switch desktop app is installed (`~/.cc-switch/cc-switch.db` exists)	SQLite database
standalone mode	cc-switch is NOT installed	JSON files (`~/.cc-switch-skill/`)

The skill automatically detects which mode to use - no manual configuration needed.

Supported Apps

Application	app_type	Hot-Switch
Codex	`Codex`	Endpoint-only
Codex	`codex`	❌ No
Gemini CLI	`gemini`	❌ No
OpenCode	`opencode`	❌ No
OpenClaw	`openclaw`	❌ No

Mode Detection

The skill checks for ~/.cc-switch/cc-switch.db:

Found → Uses SQLite mode (reads from cc-switch database)
Not found → Uses standalone mode (reads from ~/.cc-switch-skill/)

You can install/remove cc-switch anytime and the skill will automatically adapt.

Storage Locations

cc-switch Mode

Database: ~/.cc-switch/cc-switch.db
Managed by: cc-switch desktop application

Standalone Mode

Config: ~/.cc-switch-skill/config.json — Active providers per app
Providers: ~/.cc-switch-skill/providers.json — All configured providers
Presets: ~/.Codex/skills/cc-switch/presets.json — Built-in presets

Core Operations

1. Add Provider

bash

~/.Codex/skills/cc-switch/scripts/add_provider.sh \
  --name "MiniMax" \
  --app Codex \
  --key "sk-xxxx" \
  --url "https://api.minimax.com/v1" \
  --sonnet "Codex-3-5-sonnet-20241022"

2. List Providers

bash

~/.Codex/skills/cc-switch/scripts/list_providers.sh
~/.Codex/skills/cc-switch/scripts/list_providers.sh --app Codex

Output shows the current mode:

text

======================================
        Providers List
======================================

Mode: [cc-switch mode]

### Codex
ID                                      | Name                        | Status
--------------------------------------+------------------------------+--------
a1b2c3d4-e5f6-7890-abcd-ef1234567890    | Anthropic Official         | 🟢 [Active]

3. Switch Provider (with Pre-flight Connectivity Check)

bash

~/.Codex/skills/cc-switch/scripts/switch_provider.sh \
  --app Codex \
  --name "MiniMax"

Important: Switching runs a connectivity test first:

✅ Test passes → Switch proceeds automatically
❌ Test fails → Error details shown, user asked to confirm before proceeding

To skip the connectivity check (advanced use):

bash

~/.Codex/skills/cc-switch/scripts/switch_provider.sh \
  --app Codex \
  --name "MiniMax" \
  --skip-test

4. Delete Provider

bash

~/.Codex/skills/cc-switch/scripts/delete_provider.sh --id provider-uuid

Cannot delete currently active provider - must switch first.

5. Test Provider Connectivity

bash

~/.Codex/skills/cc-switch/scripts/test_connectivity.sh --app Codex --name "MiniMax"

Presets

Built-in provider presets in presets.json work in standalone mode:

Name	App	Description
Anthropic Official	Codex, gemini	Official Anthropic API
MiniMax Official	Codex	Official MiniMax API
Zhipu AI Official	Codex	Official Zhipu AI endpoint
DeepSeek Official	Codex	Official DeepSeek API

Presets are used as templates - you provide your own API key when adding.

Hot-Switching Support

Only Codex supports hot-switching — changes take effect immediately without restarting the terminal.

For all other apps, you must restart the terminal or CLI tool after switching providers.

Workflow

Typical Usage

Add provider — Use add_provider.sh with your credentials
Test — Use test_connectivity.sh to verify
Switch — Use switch_provider.sh (auto-tests first)
List — Use list_providers.sh to see all options

Example Session

text

User: I want to switch to MiniMax
Codex: Running switch_provider.sh --app Codex --name MiniMax

[Connectivity test runs...]
✅ Connectivity test passed

Switching Codex to MiniMax...
✅ Successfully switched Codex provider to: MiniMax
ℹ️ Codex supports hot-switching - changes take effect immediately!

User: Test the connection
Codex: test_connectivity.sh --app Codex --name MiniMax
[Shows detailed test results]

When Connectivity Fails

text

User: Switch to TestProvider
Codex: Running switch_provider.sh...

======================================
        Connectivity Test FAILED
======================================

Error Details:
HTTP Status: 401
API Endpoint: https://api.test.com/v1
Model: test-model

Response:
{"error": {"type": "authentication_error", "message": "Invalid API key"}}

======================================

⚠️ The connectivity test failed.
Possible causes:
  - Invalid API key
  - Incorrect base URL
  - Model name mismatch
  - Network connectivity issues

Do you want to switch to this provider anyway? (yes/no)

CLI Tool Integration

The skill manages provider configurations but updates to CLI tool settings vary:

Codex

switch_provider.sh treats Codex specially:

It reads the selected provider's base_url
It does not change cc-switch's active provider state or SQLite rows
It only merges ~/.Codex/settings.json and updates .env.ANTHROPIC_BASE_URL
It preserves the rest of settings.json

Resulting shape:

json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimax.com/v1"
  }
}

Other CLI Tools

Research the configuration file locations for:

Codex
Gemini CLI
OpenCode
OpenClaw

Update them with the active provider's API key and base URL manually.

Quick Reference

Action	Script	Connectivity Check
Add provider	`add_provider.sh`	No
List all	`list_providers.sh`	No
List by app	`list_providers.sh --app <app>`	No
Switch provider	`switch_provider.sh`	Yes (pre-flight)
Switch (skip test)	`switch_provider.sh --skip-test`	No
Delete provider	`delete_provider.sh`	No
Test connectivity	`test_connectivity.sh`	Yes (explicit)

Common Patterns

Adding a New Provider

List available presets:

bash

jq '.presets[] | select(.name)' ~/.Codex/skills/cc-switch/presets.json

Add your credentials:

bash

~/.Codex/skills/cc-switch/scripts/add_provider.sh \
  --name "My Provider" \
  --app Codex \
  --key "sk-xxxx" \
  --url "https://api.example.com/v1"

Test before switching:

bash

~/.Codex/skills/cc-switch/scripts/test_connectivity.sh --app Codex --name "My Provider"

Switch (with automatic test):

bash

~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app Codex --name "My Provider"

Managing Multiple Apps

List all providers across all apps:

bash

~/.Codex/skills/cc-switch/scripts/list_providers.sh

Switch different providers for different apps:

bash

~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app Codex --name MiniMax
~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app codex --name AnotherProvider

Troubleshooting

Script Not Found

Ensure the skill is installed in ~/.Codex/skills/cc-switch/ and scripts are executable:

bash

chmod +x ~/.Codex/skills/cc-switch/scripts/*.sh

Provider Not Found

Double-check the provider name when using --name flag:

bash

~/.Codex/skills/cc-switch/scripts/list_providers.sh

Mode Detection Issues

If you see unexpected mode:

bash

# Check if cc-switch database exists
ls -la ~/.cc-switch/cc-switch.db

# Or check standalone directory
ls -la ~/.cc-switch-skill/

Connectivity Test Always Fails

Check:

API key is correct and active
Base URL is accessible from your network
Model name is valid for the provider
Network/firewall allows the connection

Test Fails But Provider Works

If you want to switch despite test failure, use --skip-test flag:

bash

~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app Codex --name Provider --skip-test

Architecture Notes

common.sh

All scripts source scripts/common.sh which provides:

Mode detection (detect_mode())
Unified functions (list_providers(), get_provider_by_name(), etc.)
SQLite-specific functions (sqlite_*)
Standalone-specific functions (standalone_*)
Utility functions (generate_uuid(), get_provider_credentials())

Mode Auto-Switching

You can install or uninstall cc-switch at any time:

Install cc-switch → Skill automatically switches to SQLite mode on next operation
Uninstall cc-switch → Skill automatically falls back to standalone mode

No migration needed - the skill adapts to whatever is available.