cc-switch-web

cc-switch-web

Web-based CC Switch for Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw & OMO.

_{🙏 This project is a fork of farion1231/cc-switch by Jason Young. Thanks to the original author for the excellent work. This fork adds Web Server mode for cloud/headless deployment.}

Cross-platform web-based All-in-One assistant for Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw & OMO

English | 中文 | Legal Notice | Changelog

About / 项目简介

cc-switch-web is a cross-platform web-based CC Switch for Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, and oh-my-opencode (OMO). It lets you manage providers and host-side configuration from either a desktop app or an authenticated headless Web console.

Whether you’re working locally or in a headless cloud environment, cc-switch-web offers a seamless experience for:

• One-click provider switching between OpenAI-compatible API endpoints
• Unified MCP server management across Claude/Codex/Gemini/OpenCode
• Skills marketplace to browse and install Claude skills from GitHub
• System prompt editor with syntax highlighting
• Configuration backup/restore with version history
• OpenCode and OMO configuration UI with presets, model metadata, and OMO Slim support
• OpenClaw configuration center for models, Agents defaults, Environment, Tools, external Provider reconciliation, Workspace, daily memory, and sessions
• Stream health checks and retained history for validating provider streaming responses
• Web server mode for cloud/headless deployment with Basic Auth

Contact /联系

If you have any questions, you can contact me here https://linux.do/t/topic/1217545

Screenshots

Provider Switching + Local Routing	Usage Dashboard

MCP Server Management	Prompt Management

Skills Marketplace	Add Provider

Configure Provider

Features

Core Features

• Multi-Provider Management: Switch between different AI providers (OpenAI-compatible endpoints) with one click
• Unified MCP Management: Configure Model Context Protocol servers across Claude/Codex/Gemini/OpenCode
• Skills Marketplace: Browse and install Claude skills from GitHub repositories
• Prompt Management: Create and manage system prompts with a built-in CodeMirror editor
• OpenCode Provider Presets: Select AI SDK packages, import preset models, fetch model lists, and edit model variants/options
• OMO / OMO Slim UI: Manage oh-my-opencode and oh-my-opencode-slim configuration with structured fields
• OpenClaw Management: Manage additive providers, models, Agents defaults, Environment, Tools, raw JSON5, Workspace, and daily memory with ETag conflict protection and backups

Extended Features

• Backup Auto-failover: Automatically switch to backup providers when primary fails
• Stream Health Check: Test streaming responses and classify common provider errors
• Session Manager: Browse host-side Claude, Codex, Gemini, OpenCode, and OpenClaw sessions with snapshot-bound pagination and protected deletion
• Import/Export: Backup and restore all configurations with version history
• Cross-platform: Available for Windows, macOS, Linux (desktop) and Web/Docker (server)

Quick Start

Option 1: Web Server Mode (Recommended)

Recommended: Use Web Server Mode for headless/cloud deployments and remote access.

Lightweight web server for headless environments. Access via browser, no GUI dependencies.

Method A: Prebuilt Binary (Recommended)

Download precompiled server binary—no compilation required:

Release page: v0.21.0 downloads

Note (glibc): Binaries are built on Ubuntu 22.04 (glibc baseline).
If you see GLIBC_2.xx not found, use Docker or build from source.
Check your glibc with ldd --version.

One-Line Deploy:

curl -fsSL https://raw.githubusercontent.com/Laliet/cc-switch-web/main/scripts/deploy-web.sh | bash -s -- --prebuilt

Quick fixes:

• GLIBC_2.xx not found: use Docker (ghcr.io/laliet/cc-switch-web:latest) or build from source.
• Need container-first deployment: run docker run -p 3000:3000 ghcr.io/laliet/cc-switch-web:latest.
• Windows + WSL shared configs: Settings now provides a one-click WSL template path filler in Advanced tab.

Advanced options:

# Custom install directory and port
INSTALL_DIR=/opt/cc-switch PORT=8080 curl -fsSL https://raw.githubusercontent.com/Laliet/cc-switch-web/main/scripts/deploy-web.sh | bash -s -- --prebuilt

# Create systemd service for auto-start
CREATE_SERVICE=1 curl -fsSL https://raw.githubusercontent.com/Laliet/cc-switch-web/main/scripts/deploy-web.sh | bash -s -- --prebuilt

Method B: Docker Container

Docker image published to GitHub Container Registry (ghcr.io):

docker run -p 3000:3000 ghcr.io/laliet/cc-switch-web:latest

⚠️ Note: Docker image name must be lowercase (laliet, not Laliet)

Advanced Docker options:

# Use the deploy script (custom port/version/data dir/background)
./scripts/docker-deploy.sh -p 8080 --data-dir /opt/cc-switch-data -d

# Build locally (optional)
docker build -t cc-switch-web .
docker run -p 3000:3000 cc-switch-web

Method C: Build from Source

Dependencies: libssl-dev, pkg-config, Rust 1.78+, pnpm (no WebKit/GTK needed)

# 1. Clone and install dependencies
git clone https://github.com/Laliet/cc-switch-web.git
cd cc-switch-web
pnpm install

# 2. Build web assets
pnpm build:web

# 3. Build and run server
cd src-tauri
cargo build --release --no-default-features --features web-server --example server
HOST=0.0.0.0 PORT=3000 ./target/release/examples/server

Web Server Login

• Username: admin
• Password: Auto-generated on first run, stored in ~/.cc-switch/web_password
• CORS: Same-origin by default; set CORS_ALLOW_ORIGINS=https://your-domain.com for cross-origin (CORS_ALLOW_ORIGINS="*" is ignored). For LAN/private origins, enable ALLOW_LAN_CORS=1 (or CC_SWITCH_LAN_CORS=1) to auto-allow
• Note: Web mode doesn’t support native file pickers—enter paths manually

Web Runtime Boundaries

Web mode manages files and processes on the server host, not on the browser device. The runtime capability endpoint (GET /api/capabilities) drives the UI so native-only controls are not presented as working Web features.

Native file dialogs, tray integration, app update, portable-mode controls, environment management, and native endpoint testing remain desktop-only. OpenClaw local routing, MCP, prompts, skills, and usage remain intentionally unsupported because upstream v3.15.0 does not provide those OpenClaw integrations.

Security

Authentication:

• Basic Auth is required for all API requests
• Browser will prompt for credentials (username/password)
• CSRF token is automatically injected and validated for non-GET requests

Security Headers:

• HSTS (HTTP Strict Transport Security) enabled by default
• X-Frame-Options: DENY (prevents clickjacking)
• X-Content-Type-Options: nosniff
• Referrer-Policy: no-referrer

Best Practices:

• Deploy behind a reverse proxy with TLS in production
• Set ALLOW_HTTP_BASIC_OVER_HTTP=1 only if you understand the risks
• Keep ~/.cc-switch/web_password file secure (mode 0600)

Environment Variables:

Option 2: Desktop Application (GUI)

Full-featured desktop app with graphical interface, built with Tauri.

macOS Note: If you see “damaged” warning, run: xattr -cr "/Applications/CC Switch.app"

Linux AppImage: Make executable first: chmod +x CC-Switch-*.AppImage

Linux One-Line Install (recommended):

curl -fsSL https://raw.githubusercontent.com/Laliet/cc-switch-web/main/scripts/install.sh | bash

This script will:

• Auto-detect your architecture (x86_64/aarch64)
• Download the latest AppImage release
• Verify SHA256 checksum (if available)
• Install to ~/.local/bin/ccswitch (user) or /usr/local/bin/ccswitch (root)
• Create desktop entry and application icon

Advanced options:

# Install a specific release version
VERSION=v0.21.0 curl -fsSL https://...install.sh | bash

# Skip checksum verification
NO_CHECKSUM=1 curl -fsSL https://...install.sh | bash

Usage Guide

1. Adding a Provider

1. Launch CC-Switch and select your target app (Claude Code / Codex / Gemini / OpenCode / OMO)
2. Click “Add Provider” button
3. Choose a preset (e.g., OpenRouter, DeepSeek, GLM) or select “Custom”
4. Fill in:
   • Name: Display name for this provider
   • Base URL: API endpoint (e.g., https://api.openrouter.ai/v1)
   • API Key: Your API key for this provider
   • Model (optional): Specific model to use
5. Click Save

2. Switching Providers

• Click the “Enable” button on any provider card to activate it
• The active provider will be written to your CLI’s config file immediately
• Use system tray menu for quick switching without opening the app

3. Managing MCP Servers

1. Go to MCP tab
2. Click “Add Server” to configure a new MCP server
3. Choose transport type: stdio, http, or sse
4. For stdio servers, provide the command and arguments
5. Enable/disable servers with the toggle switch

4. Installing Skills (Claude only)

1. Go to Skills tab
2. Browse available skills from configured repositories
3. Click “Install” to add a skill to ~/.claude/skills/
4. Manage installed skills and add custom repositories

5. System Prompts

1. Go to Prompts tab
2. Create new prompts or edit existing ones
3. Enable a prompt to write it to the CLI’s prompt file:
   • Claude: ~/.claude/CLAUDE.md
   • Codex: ~/.codex/AGENTS.md
   • Gemini: ~/.gemini/GEMINI.md

Configuration Files

CC-Switch manages these configuration files:

CC-Switch’s runtime store: ~/.cc-switch/cc-switch.db

Legacy import/export snapshot: ~/.cc-switch/config.json. On startup, an existing snapshot is imported into SQLite when the database is empty; after that SQLite is the authoritative store for providers, MCP servers, prompts, skills, proxy settings, provider health, request logs, failover queue entries, and compatible JSON snapshots used by import/export flows.

v0.21.0 continues to use SQLite Schema v7, which includes retained Stream Check history. WebDAV v2 writes new snapshots under v2/db-v7/<profile>/, still reads and restores v0.19.1 db-v6 snapshots/history, and keeps the legacy 0.18 JSON snapshot as a read-only migration source. Runtime logs, usage data, health state, session sync state, and Stream Check history are not uploaded; existing local diagnostic history is preserved during restore.

Development

# Install dependencies
pnpm install

# Run desktop app in dev mode
pnpm tauri dev

# Run only the frontend dev server
pnpm dev:renderer

# Build desktop app
pnpm tauri build

# Build web assets only
pnpm build:web

# Run tests
pnpm test:unit

Tech Stack

• Frontend: React 18, TypeScript, Vite, Tailwind CSS, TanStack Query, Radix UI, CodeMirror
• Backend: Rust, Tauri 2.x, Axum (web server mode), tower-http
• Tooling: pnpm, Vitest, MSW

What’s New

Current release: v0.21.0
v0.21.0 completes OpenClaw phase two, global Session search, installed-Skills discovery, and Provider routing visibility.

v0.21.0 - OpenClaw Phase Two

• Completes structured OpenClaw models, Agents defaults, Environment, Tools/Profile, and advanced raw JSON5 editing
• Adds external Provider reconciliation with ETag-bound preview/apply and idempotent startup refresh
• Adds host-wide Session search plus virtualized long-conversation messages and outlines
• Adds installed-Skills discovery/import with trusted roots, conflict preview, explicit overwrite, and multi-app synchronization
• Adds Daily Memory search and backed-up ETag-protected deletion
• Merges all upstream v3.15.0 OpenClaw, Gemini, and Codex presets while retaining local China-accessible entries
• Shows failover priority, actual proxy route, circuit state/failures, and latest health-check time on Provider cards
• Release notes: v0.21.0

v0.20.0 - Web/Headless + OpenClaw Phase One

• Adds an explicit desktop/Web capability contract and host-bound UI behavior
• Adds OpenClaw phase-one provider/default-model, Workspace/daily-memory, and Session Manager workflows
• Persists Stream Check configuration/history in Schema v7 and adds provider quota summaries
• Adds real HTTP proxy conformance coverage, more precise usage parsing, stable failover ordering, and Claude Desktop restart-state detection
• Hardens Session pagination/path handling, Web error disclosure, WebDAV v6 fallback, and manifest identity validation
• Keeps OMO/OMO Slim MCP and Skills on shared OpenCode storage while continuing to reject OMO proxy takeover
• Pins the upstream v3.15.0 comparison baseline in docs/upstream-v3.15.0.lock
• Release notes: v0.20.0

v0.19.1 - Release Quality Patch

• Keeps the v0.19.0 runtime behavior unchanged
• Fixes the Skills update result sorting implementation so the source passes Clippy with warnings denied
• Release notes: v0.19.1

v0.19.0 - Data Safety + Relay Workflow Completion

• Adds native SQLite SQL backup/restore, integrity validation, rollback, backup management, and scheduled retention
• Introduces WebDAV v2 with manifest.json, db.sql, skills.zip, checksums, compatibility validation, rollback, and change-triggered synchronization
• Adds native quota/balance queries for common relay providers without requiring user-authored JavaScript
• Completes Universal Provider, MCP import, Skills update/catalog, and per-app proxy settings workflows
• Adds a server-host Session Manager for Claude, Codex, Gemini, and OpenCode with search, messages, outline, deletion, and copied resume commands
• Release notes: v0.19.0

v0.15.0 - Local Routing + Claude Desktop Alignment

• Adds the stable Local Routing and Claude Desktop alignment release line
• Improves Usage Dashboard first-load behavior with automatic Recent data range selection when Today has no requests
• Adds the All time usage range and clarifies all-time data source statistics
• Adds usage data extent APIs for desktop and Web/headless mode
• Fixes Web-mode unmatched /api/* routes so they return JSON 404 responses instead of SPA HTML fallback
• Adds clearer frontend API failure toasts and inline Usage Dashboard error states
• Release notes: v0.15.0

v0.14.1 - Usage Dashboard Patch

• Fixes Usage Dashboard auto-refresh so relative time ranges recompute on each refetch
• Fixes request logs pagination reset when changing the global app or time range
• Fixes short historical trend queries that only have daily rollup data
• Tightens model-pricing matching so broad prefixes such as gpt-4 do not misprice gpt-4o
• Release notes: v0.14.1

v0.14.0 - Usage Dashboard Prerelease

• Adds a full Usage Dashboard for proxy-backed requests, with cost summary, token breakdown, app split, trend chart, and refresh controls
• Adds searchable/paginated request logs with per-request token, latency, status, streaming, and cost detail
• Adds Provider and Model usage statistics plus a Dashboard pricing editor for model cost configuration
• Connects pricing updates to historical zero-cost proxy logs so newly configured model prices can backfill costs
• Adds Claude, Codex, and Gemini session log import with incremental sync and cross-source de-duplication
• Adds desktop and Web/headless Usage APIs under Tauri commands and /api/usage/*
• Release notes: v0.14.0

Changelog

See CHANGELOG.md and v0.21.0 release notes - Current release: v0.21.0

Credits

This project is a fork of cc-switch by Jason Young (farion1231). We sincerely thank the original author for creating such an excellent foundation. Without the upstream project’s pioneering work, cc-switch-web would not exist.

The upstream Tauri desktop app unified provider switching, MCP management, skills, and prompts with strong i18n and safety. cc-switch-web adds web/server runtime, CORS controls, Basic Auth, more templates, and documentation for cloud/headless deployment.

Legal & Compliance Summary

• Allowed scope: learning, research, self-hosting experimentation, and community communication.
• Prohibited uses: unlawful activity, infringement, unauthorized data collection, bypassing platform/service restrictions, evading rate limits or access controls, abusing other people’s accounts / API keys / credentials, or violating third-party terms.
• Third-party terms prevail: when using services or tools from OpenAI, Anthropic, Google Gemini, OpenCode, OMO, cloud vendors, hosting providers, or any other third party, you must independently review and comply with their applicable terms, policies, and usage rules. If this project’s documentation conflicts with those rules, applicable law and the third party’s binding terms prevail.
• Further notice: see LEGAL_NOTICE.md. The open-source license text is in LICENSE, with supplementary notice in LICENSE_NOTICE.md.

License

MIT License — See LICENSE for details.