CC Switch: Chuyển provider AI coding agent một cú nhấp

Bạn đang chạy Claude Code thì hết quota, chuyển sang Codex lại chạm rate limit, rồi muốn thử một model khác trên Gemini CLI. Mỗi lần như vậy, bạn lại mở file cấu hình, sửa key, sửa endpoint, sửa tên model, rồi khởi động lại công cụ và hy vọng mình không gõ sai ký tự nào.

CC Switch xử lý đúng điểm đau đó: ứng dụng desktop quản lý provider cho nhiều AI coding agent, cho phép chọn provider đang dùng bằng một cú nhấp thay vì sửa tay từng file JSON, TOML hay .env. Thông tin trong bài đối chiếu với bản v4.0.21 ngày 26/10/2026, kiểm tra ngày 28/10/2026. Các lệnh dưới đây đối chiếu tài liệu chính thức, chưa chạy thử.

Vấn đề thật: vì sao đổi provider lại mệt đến vậy?

Mỗi AI coding CLI có một nơi lưu cấu hình riêng và một định dạng riêng: Claude Code dùng settings.json, Codex dùng config.toml, Gemini CLI lại liên quan tới file .env. Sửa tay tạo thêm rủi ro: một dấu phẩy thừa trong JSON, một tên model gõ sai, một key dán nhầm từ provider khác. Rủi ro lớn hơn là key rất dễ đi lạc nếu file cấu hình chứa key vô tình được đưa vào git hay sao lưu lên chỗ không an toàn.

Dev phải đổi provider trong ngày vì nhiều lý do: hết quota, chạm rate limit, đổi model cho một tác vụ cụ thể, đổi key team khi key cũ hết hạn hoặc bị thu hồi. Điểm chung là bạn cần đổi nhanh, đổi đúng, và quay lại làm việc ngay. CC Switch giải quyết khâu chuyển đổi: chọn provider, áp dụng vào cấu hình gốc, và cho bạn biết provider nào đang active. Nó không giải quyết bài toán quản lý tập trung cho cả team ở tầng server.

CC Switch là gì?

CC Switch là ứng dụng desktop đa nền tảng, xây dựng trên Tauri 2, phát hành theo giấy phép MIT. Kho mã nguồn chính thức là farion1231/cc-switch, trang web chính thức là ccswitch.io. Tại thời điểm kiểm tra ngày 28/10/2026, dự án có khoảng 149.500 star trên GitHub và bản mới nhất là v4.0.21, cập nhật gần nhất trong cùng ngày.

Danh sách hỗ trợ gồm Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code, Kimi Code và Oh My Pi. Chỉ cần thường xuyên chuyển đổi giữa hai hoặc ba CLI, việc gom chúng về một chỗ đã đáng giá. Theo mình, CC Switch phù hợp nhất với dev dùng nhiều AI coding CLI trong ngày, sysadmin và DevOps phụ trách máy dev, và người muốn đổi provider nhanh mà không dựng thêm hạ tầng. Ngược lại, nếu bạn cần kiểm soát chung cho cả team, CC Switch không thay được gateway, và máy chạy RHEL, Rocky hay AlmaLinux 8–9 hiện chưa được hỗ trợ.

Cách CC Switch hoạt động

Điểm quan trọng nhất là CC Switch không phải gateway thường trực và cũng không thay thế các CLI bạn đang dùng. Khi bạn chọn một provider, CC Switch ghi provider và key đang active vào file cấu hình gốc của công cụ đó. Sau cú nhấp đó, CLI chạy như bình thường, và bạn có thể tắt CC Switch mà phiên làm việc vẫn tiếp tục, trừ khi bạn đang dùng routing. Thiết kế này làm rollback rất rẻ: muốn quay lại provider cũ, chỉ cần chọn lại provider đó. Đổi lại, CC Switch phụ thuộc vào định dạng cấu hình của từng CLI; nếu một CLI thay đổi định dạng file, tính năng đồng bộ có thể lệch cho tới khi ứng dụng cập nhật theo.

Không phải công cụ nào cũng hoạt động giống nhau. Nhóm Switch chỉ có một provider active tại một thời điểm, gồm Claude Code, Claude Desktop, Codex, Gemini CLI và Grok Build. Nhóm Coexist cho phép nhiều provider cùng tồn tại, gồm OpenCode, OpenClaw, Hermes, MiniMax Code, Kimi Code, Pi và Oh My Pi. Luồng làm việc gồm ba bước: thêm provider, nhấn Enable, rồi khởi động lại công cụ theo đúng quy tắc của nó. System tray là nơi chuyển đổi nhanh nhất: mỗi công cụ có một dòng gồm tên, chế độ và provider đang dùng.

CC Switch có ba cách kết nối. Direct là mặc định: CLI kết nối thẳng tới provider đã chọn. Theo mình, đây nên là lựa chọn mặc định, vì ít lớp trung gian nhất và dễ chẩn đoán lỗi nhất. Routing chuyển request qua máy local, với chuyển đổi định dạng API và failover; routing chỉ có cho Claude Code, Codex, Gemini CLI và Grok Build. Nó thêm độ trễ và khả năng lỗi định dạng, nên khi gặp sự cố lúc bật routing, hãy quay về Direct trước. Aggregation chỉ có ý nghĩa với Claude Code và Codex: gộp model từ nhiều provider vào một danh sách chung.

Ngoài provider, CC Switch cho phép quản lý tập trung MCP, Skills và Prompts: thêm một lần, rồi chọn những công cụ nào sẽ đồng bộ. Cấu hình đang active nằm trong file cấu hình gốc của từng CLI, còn trạng thái riêng của CC Switch lưu tại ~/.cc-switch/cc-switch.db.

Cài đặt theo từng hệ điều hành

Phiên bản tham chiếu là v4.0.21, phát hành ngày 26/10/2026. Yêu cầu hệ thống gồm Windows 10 trở lên, macOS 12 trở lên, và Linux x86_64 hoặc ARM64 với glibc 2.35 trở lên cùng WebKitGTK 4.1 — ví dụ Ubuntu 22.04 trở lên và Debian 12 trở lên. RHEL, Rocky và AlmaLinux 8–9 hiện chưa được hỗ trợ.

Trên macOS, dùng Homebrew: brew install --cask cc-switch, cập nhật bằng brew upgrade --cask cc-switch. Nếu không dùng Homebrew, tải file .dmg hoặc .zip từ trang Releases; bản macOS là bản Universal, đã được ký và notarize. Trên Windows, tải file .msi hoặc bản Portable .zip từ trang Releases, có cả bản x64 và ARM64; hãy chọn đúng kiến trúc. Trên Linux, tải .deb, .rpm hoặc .AppImage theo đúng kiến trúc x86_64 hay ARM64. Không có Flatpak chính thức. Nếu máy thiếu WebKitGTK 4.1, hãy cài WebKitGTK từ kho phần mềm của bản phân phối trước khi thử lại. Trên Arch, dùng paru -S cc-switch-bin.

Kết quả mong đợi sau khi cài là giao diện liệt kê từng công cụ, provider đang active và trạng thái quota nếu provider cung cấp thông tin này. Nếu chưa thêm provider nào, danh sách có thể trống hoặc chỉ hiển thị provider mặc định. Ba lỗi thường gặp là: công cụ không hiện, tải sai gói, và thiếu WebKitGTK trên Linux.

Chuyển provider lần đầu

Thêm provider từ preset có sẵn hoặc cấu hình tùy chỉnh với endpoint và key của mình. Với key chính, theo mình nên ưu tiên key của chính mình thay vì dùng relay lạ chỉ vì nó xuất hiện sẵn trong danh sách. Tài liệu của dự án có kèm các vị trí tài trợ, và relay tài trợ không đồng nghĩa với khuyến nghị bảo mật.

Sau khi thêm provider, nhấn Enable để đặt nó thành provider đang active. Với nhóm Switch, thao tác này thay thế provider trước đó; với nhóm Coexist, bạn bổ sung provider vào danh sách dùng chung.

Bước nhiều người bỏ qua nhất là quy tắc khởi động lại. Claude Code không cần khởi động lại. Codex, Gemini CLI và Grok Build cần khởi động lại CLI, tức là đóng terminal đang chạy và mở lại. Claude Desktop cần khởi động lại ứng dụng. Nếu terminal cũ vẫn mở, CLI có thể tiếp tục dùng cấu hình cũ và bạn sẽ tưởng CC Switch chuyển thất bại.

Khi muốn quay về đăng nhập chính thức, chọn provider official tích hợp sẵn, ví dụ “Claude Official”, khởi động lại công cụ theo quy tắc của nó, rồi đi theo luồng OAuth của công cụ. Đây cũng là đường rollback nhanh nhất khi key API gặp sự cố. Thẻ provider và system tray hiển thị usage và quota khi provider cung cấp thông tin này; hãy nhìn vào đó trước khi bắt đầu một tác vụ dài.

Đánh giá: ưu điểm, nhược điểm, bảo mật và vận hành

Ưu điểm rõ nhất là tốc độ đổi provider và việc giảm lỗi sửa tay. Một giao diện cho nhiều CLI giúp bạn không phải nhớ từng đường dẫn file cấu hình. Việc giữ nguyên file cấu hình gốc giúp CLI vẫn chạy native.

Nhược điểm lớn nhất là tính năng không đồng đều giữa các công cụ: routing, aggregation và coexist khác nhau theo từng nhóm. Nhược điểm thứ hai là sự phụ thuộc vào định dạng cấu hình của CLI: CLI cập nhật có thể làm lệch đồng bộ. Nhược điểm thứ ba là phạm vi quản lý chỉ ở cấp máy đơn lẻ, không có trạng thái chung cho team.

Về bảo mật, key nằm trên máy dev, trong file cấu hình của CLI và cơ sở dữ liệu của CC Switch. Vì vậy, tuyệt đối không commit file cấu hình chứa key lên git, và không sao lưu thư mục cấu hình lên nơi không kiểm soát mà không mã hóa. Hãy thêm các file cấu hình chứa key vào .gitignore. Nếu bạn nghi ngờ key đã lộ, hãy xoay key ngay ở phía provider, rồi mới cập nhật trong CC Switch. Bài viết về Heldkeys làm một việc khác — kiểm tra quyền truy cập thay vì chuyển provider — và đáng đọc thêm tại: Heldkeys: kiểm tra quyền truy cập của AI agent.

Tài liệu chính thức không công bố số liệu hiệu năng, tiết kiệm token hay tiết kiệm chi phí, nên bài viết này không đưa ra kết luận nào về các con số đó. Trong vận hành hàng ngày, hãy sao lưu file cấu hình gốc trước khi đổi provider lần đầu, kiểm tra lại provider đang active sau mỗi lần CLI cập nhật, và chọn một nguồn thay đổi duy nhất.

So sánh với các cách quản lý provider cùng phạm vi

Tiêu chí so sánh gồm: tốc độ đổi provider, rủi ro sai cấu hình, quản lý nhiều công cụ, quản lý tập trung cho team, kiểm soát quota và billing, và phụ thuộc vào server. Sửa tay không cần cài thêm ứng dụng, nhưng tốc độ chậm, dễ sai, và khó duy trì khi số công cụ tăng lên. CC Switch nhanh hơn và gom nhiều công cụ về một chỗ, nhưng bạn phải chấp nhận thêm một ứng dụng desktop. Theo mình, nếu chỉ dùng một CLI và hiếm khi đổi provider, sửa tay vẫn đủ. Nếu đổi provider nhiều lần trong tuần và dùng từ hai CLI trở lên, CC Switch bắt đầu xứng đáng.

Cặp so sánh quan trọng nhất là CC Switch phía client với New API gateway phía server. Hai công cụ này bổ sung cho nhau chứ không thay thế nhau. CC Switch nhanh, không cần server, phù hợp với máy dev cá nhân, nhưng không có quota, billing hay audit chung cho team. New API gom nhiều LLM về một endpoint và quản lý tập trung, nhưng bạn phải dựng và vận hành thêm một dịch vụ. Bạn có thể dùng cả hai: New API làm tầng gateway chung, CC Switch giúp đổi nhanh trên máy dev. Đọc thêm về tầng gateway tại: Tự host New API AI gateway.

Use case, xử lý sự cố, rollback và kết luận

Với dev dùng nhiều AI coding agent trong ngày, CC Switch giúp đổi trong vài thao tác thay vì mở từng file cấu hình. Với DevOps và IT admin, nó giúp hướng dẫn đổi key trở nên thống nhất, nhưng đây vẫn là chuẩn hóa ở cấp máy, chưa phải quản lý ép buộc từ server. Trên máy cá nhân hoặc homelab, CC Switch cho phép thử nhiều provider mà không cần dựng thêm gateway. Ở cấp doanh nghiệp, theo mình, nó phù hợp ở cấp workstation, chưa thay được gateway tập trung. Headroom là công cụ khác phạm vi, tập trung vào nén context: Headroom: nén context cho AI agent.

Về xử lý sự cố, lỗi thường gặp nhất là đã chuyển nhưng CLI vẫn dùng key cũ, và nguyên nhân thường là chưa tuân thủ quy tắc restart: Claude Code không cần restart, Codex, Gemini CLI và Grok Build cần restart CLI, Claude Desktop cần restart app. Hãy kiểm tra xem bạn có đang sửa tay song song với CC Switch hay không, vì thao tác đó có thể ghi đè provider vừa chọn. Nếu gặp lỗi sau khi bật routing, hãy chuyển về Direct và thử lại.

Rủi ro lớn nhất không nằm ở việc chuyển provider, mà ở chỗ key lưu trên máy dev. Máy bị chia sẻ, bị mất, hoặc được sao lưu không cẩn thận đều có thể kéo theo rủi ro lộ key. Hãy giữ máy dev an toàn, không commit file cấu hình chứa key, và xoay key ngay khi nghi ngờ lộ. Rollback rất rẻ: chọn lại provider official hoặc provider trước đó, rồi khởi động lại công cụ theo đúng quy tắc của nó. Để gỡ CC Switch, gỡ ứng dụng như bình thường: file cấu hình gốc vẫn còn, và công cụ tiếp tục chạy với provider cuối cùng.

Tóm lại, CC Switch phù hợp với dev dùng nhiều AI coding CLI, người thường xuyên đổi provider vì quota hoặc đổi model, và người muốn quản lý nhanh phía client mà không dựng thêm gateway. Nó không phù hợp với team cần gateway, quota, billing và audit tập trung, hoặc với máy chạy RHEL 8/9 chưa được hỗ trợ. Bước tiếp theo theo mình là thận trọng: cài đúng gói theo hệ điều hành, rồi đổi thử một provider phụ trước khi chuyển key chính.

Tài liệu tham khảo

• Kho mã nguồn chính thức CC Switch: https://github.com/farion1231/cc-switch
• Trang web chính thức: https://ccswitch.io
• Trang Releases, bản v4.0.21 ngày 26/10/2026: https://github.com/farion1231/cc-switch/releases