Claude Code, Codex, Gemini CLI, OpenCode 및 OMO를 위한 웹 기반 CC Switch.

🙏 이 프로젝트는 Jason Young의 farion1231/cc-switch를 포크(fork)한 것입니다. 훌륭한 작업을 해준 원작자에게 감사드립니다. 이 포크 버전은 클라우드/헤드리스(headless) 배포를 위한 웹 서버(Web Server) 모드를 추가했습니다.

Claude Code, Codex, Gemini CLI, OpenCode 및 OMO를 위한 크로스 플랫폼 웹 기반 올인원(All-in-One) 어시스턴트

영어 | 중국어 | 법적 고지 | 변경 로그 (Changelog)

권장 안정 버전: v0.11.1

v0.11.1은 현재 안정 버전입니다.

cc-switch-web은 Claude Code, Codex, Gemini CLI, OpenCode, 그리고 **oh-my-opencode (OMO)**를 위한 크로스 플랫폼 웹 기반 CC Switch입니다. 이를 통해 제공자(provider)를 전환하고, MCP 서버를 관리하며, 스킬(skills)을 설치하고, 시스템 프롬프트(system prompts)를 편집할 수 있으며, 데스크톱 또는 헤드리스 클라우드 환경에서 동일한 워크플로우를 실행할 수 있습니다.

로컬에서 작업하든 헤드리스 클라우드 환경에서 작업하든, cc-switch-web은 다음과 같은 원활한 경험을 제공합니다:

OpenAI 호환 API 엔드포인트 간의 클릭 한 번으로 제공자 전환
Claude/Codex/Gemini/OpenCode 전반에 걸친 통합 MCP 서버 관리
GitHub에서 Claude 스킬을 찾아 설치할 수 있는 스킬 마켓플레이스(Skills marketplace)
구문 강조(syntax highlighting) 기능이 포함된 시스템 프롬프트 에디터
버전 기록이 포함된 설정 백업/복구
Basic Auth를 통한 클라우드/헤드리스 배포용 웹 서버 모드

질문이 있으시면 여기로 문의해 주세요: https://linux.do/t/topic/1217545

• React 이전에 i18n 벤더 청크(vendor chunk)가 로드되어 로그인 후 빈 페이지가 표시될 수 있는 Docker/Web 배포 관련 핫픽스(Hotfix) 적용

• react-i18next가 React 벤더 청크에 유지되도록 웹 청킹(Web chunking)에 대한 회귀 테스트(regression coverage) 추가 - 전체 Dockerfile 빌드 및 브라우저 수준의 컨테이너 스모크 테스트(smoke test)로 검증 완료

• 릴리스 노트: v0.11.1

• Web/headless 로컬 HTTP 포워드 프록시 (forward proxy) 워크플로우의 안정화 버전 (Stable release) 출시

• 프록시 시작, 중지, 상태, 테스트, 자동 시작, 로그 및 클라이언트별 테이크오버(takeover)/복구(restore)를 위한 설정 (Settings) 제어 추가

• Claude Code, Codex, Gemini CLI 및 실험적 단계인 OpenCode에 대한 프록시 테이크오버 지원

• 외부 env 객체가 보존되도록 Claude 프로바이더 (provider) JSON 포맷팅 수정

• skills/skills/* 설치를 방지하기 위해 Anthropic Skills 저장소의 기본 스캔 경로 수정

• OMO MCP / Skills 엔트리 포인트 (entry points) 개선 및 OMO Skills가 OpenCode 스토리지를 재사용함을 명시

• 릴리스 노트: v0.11.0

• Web/headless 프록시 안정화 버전 출시 이전의 이전 안정 버전

• 이전 안정 빌드는 다음에서 다운로드 가능: v0.10.1

• OpenCode 프로바이더 (provider) 관리 및 자동 OpenCode 설정 쓰기 기능 추가

• oh-my-opencode (OMO) 설정 관리 및 플러그인 동기화 지원 추가

• 설정 (Settings)에서 Web 모드 로그인 사용자 이름/비밀번호를 직접 업데이트할 수 있도록 허용

• OMO/OpenCode 연결 쓰기 및 현재 프로바이더 편집에 대한 롤백 (rollback) 안전성 개선
  v0.10.0은 이 릴리스 라인의 검증용 프리릴리스 (prerelease) 마일스톤이었습니다.

• Web 모드는 프라이빗 LAN 자동 허용을 위해 동일 출처 CORS (same-origin CORS)인 ALLOW_LAN_CORS=1 / CC_SWITCH_LAN_CORS=1을 기본값으로 사용합니다 - 원격 배포를 위한 더 안전한 기본 동작

멀티 프로바이더 관리 (Multi-Provider Management): 클릭 한 번으로 서로 다른 AI 프로바이더 (OpenAI 호환 엔드포인트) 간 전환 가능
통합 MCP 관리 (Unified MCP Management): Claude/Codex/Gemini/OpenCode 전반에 걸쳐 모델 컨텍스트 프로토콜 (Model Context Protocol) 서버 구성
Skills 마켓플레이스 (Skills Marketplace): GitHub 저장소에서 Claude 스킬을 찾아 설치
프롬프트 관리 (Prompt Management): 내장된 CodeMirror 에디터로 시스템 프롬프트 생성 및 관리

백업 자동 장애 조치 (Backup Auto-failover): 기본 프로바이더 실패 시 백업 프로바이더로 자동 전환
가져오기/내보내기 (Import/Export): 버전 기록과 함께 모든 설정을 백업 및 복구
크로스 플랫폼 (Cross-platform): Windows, macOS, Linux (데스크톱) 및 Web/Docker (서버)에서 사용 가능

권장 사항: 헤드리스 (headless)/클라우드 배포 및 원격 액세스에는 Web 서버 모드를 사용하십시오.

헤드리스 (headless) 환경을 위한 경량 웹 서버 (Lightweight web server). 브라우저를 통해 액세스하며, GUI 의존성이 없습니다.

컴파일이 필요 없는 사전 컴파일된 서버 바이너리 (precompiled server binary)를 다운로드하십시오:

참고 (glibc): 바이너리는 Ubuntu 22.04 (glibc 기준점)에서 빌드되었습니다.

GLIBC_2.xx not found 오류가 발생하는 경우, Docker를 사용하거나 소스에서 직접 빌드하십시오.

ldd --version 명령어로 glibc 버전을 확인하십시오.

한 줄 배포 (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: Docker (ghcr.io/laliet/cc-switch-web:latest)를 사용하거나 소스에서 직접 빌드하십시오.

• 컨테이너 우선 배포 (container-first deployment)가 필요한 경우: docker run -p 3000:3000 ghcr.io/laliet/cc-switch-web:latest를 실행하십시오.
• Windows + WSL 공유 설정: 이제 설정 (Settings)의 고급 (Advanced) 탭에서 클릭 한 번으로 WSL 템플릿 경로를 채워주는 기능을 제공합니다.

고급 옵션 (Advanced options):

# 사용자 정의 설치 디렉토리 및 포트
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
# 자동 시작을 위한 systemd 서비스 생성
...

Docker 이미지는 GitHub Container Registry (ghcr.io)에 게시되었습니다:

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

⚠️ 주의: Docker 이미지 이름은 반드시 소문자여야 합니다 (laliet, Laliet 아님).

고급 Docker 옵션 (Advanced Docker options):

# 배포 스크립트 사용 (사용자 정의 포트/버전/데이터 디렉토리/백그라운드)
./scripts/docker-deploy.sh -p 8080 --data-dir /opt/cc-switch-data -d
# 로컬에서 빌드 (선택 사항)
...

의존성 (Dependencies): libssl-dev, pkg-config, Rust 1.78+, pnpm (WebKit/GTK 불필요)

# 1. 클론(Clone) 및 의존성 설치
git clone https://github.com/Laliet/cc-switch-web.git
cd cc-switch-web
...

사용자 이름 (Username): admin

비밀번호 (Password): 첫 실행 시 자동 생성되며, ~/.cc-switch/web_password에 저장됩니다.

CORS: 기본적으로 동일 출처(Same-origin) 정책이 적용됩니다. 교차 출처(Cross-origin)를 허용하려면 CORS_ALLOW_ORIGINS=https://your-domain.com을 설정하십시오 (CORS_ALLOW_ORIGINS="*"는 무시됩니다). LAN/개인 네트워크 출처의 경우, ALLOW_LAN_CORS=1 (또는 CC_SWITCH_LAN_CORS=1)을 활성화하여 자동으로 허용할 수 있습니다.

참고: 웹 모드(Web mode)는 네이티브 파일 선택기(File picker)를 지원하지 않으므로 경로를 수동으로 입력해야 합니다.

인증 (Authentication):

• 모든 API 요청에는 기본 인증 (Basic Auth)이 필요합니다.
• 브라우저에서 자격 증명(사용자 이름/비밀번호) 입력을 요청합니다.
• GET 이외의 요청에 대해서는 CSRF 토큰이 자동으로 주입되고 검증됩니다.

보안 헤더 (Security Headers):

• HSTS (HTTP Strict Transport Security)가 기본적으로 활성화되어 있습니다.
• X-Frame-Options: DENY (클릭재킹 (Clickjacking) 방지)
• X-Content-Type-Options: nosniff
• Referrer-Policy: no-referrer

권장 사항 (Best Practices):

• 운영 환경에서는 TLS가 적용된 리버스 프록시 (Reverse proxy) 뒤에 배포하십시오.
• 위험성을 충분히 이해한 경우에만 ALLOW_HTTP_BASIC_OVER_HTTP=1을 설정하십시오.
• ~/.cc-switch/web_password 파일을 안전하게 관리하십시오 (권한 모드 0600).

환경 변수 (Environment Variables):

Tauri로 구축된 그래픽 인터페이스를 갖춘 풀 기능 데스크톱 앱입니다.

macOS 참고 사항: "손상됨" 경고가 나타나면 다음 명령어를 실행하세요: xattr -cr "/Applications/CC Switch.app"

Linux AppImage: 먼저 실행 권한을 부여해야 합니다: chmod +x CC-Switch-*.AppImage

Linux 원라인 설치 (One-Line Install) (권장):

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

이 스크립트는 다음 작업을 수행합니다:

• 아키텍처 (x86_64/aarch64) 자동 감지
• 최신 AppImage 릴리스 다운로드
• SHA256 체크섬 (Checksum) 검증 (사용 가능한 경우)
• 다음 경로에 설치:
  • ~/.local/bin/ccswitch (사용자 권한)
  • /usr/local/bin/ccswitch (루트 권한)
• 데스크톱 엔트리(Desktop entry) 및 애플리케이션 아이콘 생성

고급 옵션 (Advanced options):

# 현재 안정 버전을 설치
VERSION=v0.11.1 curl -fsSL https://...install.sh | bash
# 체크섬 검증 건너뛰기
...

• CC-Switch를 실행하고 대상 앱 (Claude Code / Codex / Gemini / OpenCode / OMO)을 선택합니다.

• "Add Provider" 버튼을 클릭합니다. - 프리셋 (예: OpenRouter, DeepSeek, GLM)을 선택하거나 "Custom"을 선택합니다.

• 다음 항목을 입력합니다:

  • Name: 이 프로바이더의 표시 이름
  • Base URL: API 엔드포인트 (예: https://api.openrouter.ai/v1)
  • API Key: 이 프로바이더를 위한 API 키
  • Model (선택 사항): 사용할 특정 모델

• Save를 클릭합니다.

• 프로바이더 카드에 있는 "Enable" 버튼을 클릭하여 활성화합니다. - 활성화된 프로바이더는 즉시 CLI의 설정 파일(Config file)에 기록됩니다.

• 앱을 열지 않고도 시스템 트레이 메뉴를 사용하여 빠르게 전환할 수 있습니다.

• MCP 탭으로 이동합니다. - **"Add Server"**를 클릭하여 새로운 MCP 서버를 구성합니다. - 전송 방식 (Transport type)을 선택합니다: stdio, http, 또는 sse

• stdio 서버의 경우, 명령어와 인자(Arguments)를 제공합니다.

• 토글 스위치로 서버를 활성화/비활성화합니다.

• Skills 탭으로 이동합니다. - 구성된 리포지토리(Repositories)에서 사용 가능한 스킬을 찾아봅니다.

• **"Install"**을 클릭하여 ~/.claude/skills/에 스킬을 추가합니다.

• 설치된 스킬을 관리하고 커스텀 리포지토리를 추가합니다.

• Prompts 탭으로 이동합니다. - 새로운 프롬프트를 생성하거나 기존 프롬프트를 편집합니다.

• 프롬프트를 활성화하면 CLI의 프롬프트 파일에 기록됩니다:

  • Claude: ~/.claude/CLAUDE.md
  • Codex: ~/.codex/AGENTS.md

• Gemini:
  ~/.gemini/GEMINI.md

• Claude:

CC-Switch는 다음의 설정 파일들을 관리합니다:

CC-Switch 자체 설정: ~/.cc-switch/config.json

# 의존성 설치
pnpm install
# 개발 모드에서 데스크톱 앱 실행
...

프론트엔드 (Frontend): React 18, TypeScript, Vite, Tailwind CSS, TanStack Query, Radix UI, CodeMirror
백엔드 (Backend): Rust, Tauri 2.x, Axum (웹 서버 모드), tower-http
도구 (Tooling): pnpm, Vitest, MSW

CHANGELOG.md를 참조하세요 — 권장 안정 버전: v0.11.1

이 프로젝트는 Jason Young (farion1231)의 cc-switch를 포크(fork)한 것입니다. 이토록 훌륭한 기반을 만들어준 원작자에게 진심으로 감사드립니다. 업스트림(upstream) 프로젝트의 선구적인 작업이 없었다면 cc-switch-web은 존재하지 않았을 것입니다.

업스트림 Tauri 데스크톱 앱은 강력한 국제화 (i18n) 및 안전성을 바탕으로 프로바이더 전환, MCP 관리, 스킬(skills), 프롬프트(prompts)를 통합했습니다. cc-switch-web은 웹/서버 런타임, CORS 제어, 기본 인증 (Basic Auth), 더 많은 템플릿, 그리고 클라우드/헤드리스 (headless) 배포를 위한 문서를 추가합니다.

경고 (Warning)

이 프로젝트는 학습, 연구 및 커뮤니티 교류 목적으로만 제공됩니다. 사용하기 전에 의도한 사용이 관련 법률, 규정, 플랫폼 규칙 및 제3자 서비스 약관을 준수하는지 신중하게 평가하십시오.

이 프로젝트를 사용함으로써, 귀하는 본인의 설정, 배포 및 사용으로 인해 발생하는 위험을 평가하고 부담하는 데 동의합니다. 관련 법률이 허용하는 최대 범위 내에서, 이 프로젝트는 명시적 또는 묵시적인 어떠한 보증 없이 "있는 그대로 (AS IS)" 제공됩니다.

이 고지는 모든 법적 위험을 완전히 배제하거나 포기할 수 있음을 의미하지 않습니다. 관련 법률에 따라 배제하거나 제한할 수 없는 책임은 여전히 관련 법률의 적용을 받습니다.

허용 범위: 학습, 연구, 셀프 호스팅 (self-hosting) 실험 및 커뮤니티 소통.금지된 사용: 불법 활동, 침해, 승인되지 않은 데이터 수집, 플랫폼/서비스 제한 우회, 속도 제한 (rate limits) 또는 액세스 제어 (access controls) 회피, 타인의 계정 / API 키 / 자격 증명 (credentials) 남용, 또는 제3자의 약관 위반.제3자 약관 우선: OpenAI, Anthropic, Google Gemini, OpenCode, OMO, 클라우드 벤더, 호스팅 제공업체 또는 기타 제3자의 서비스나 도구를 사용할 때는 해당 서비스의 관련 약관, 정책 및 사용 규칙을 독립적으로 검토하고 준수해야 합니다. 본 프로젝트의 문서가 해당 규칙과 충돌하는 경우, **관련 법률 및 제3자의 구속력 있는 약관이 우선합니다.**추가 고지: LEGAL_NOTICE.md를 참조하십시오. 오픈 소스 라이선스 (open-source license) 텍스트는 LICENSE에 있으며, 추가 고지 사항은 LICENSE_NOTICE.md에 있습니다.

MIT License — 자세한 내용은 LICENSE를 참조하십시오.