Bởi Matt Connor 2026-10-01

CC Switch: đổi nhà cung cấp API cho Claude Code an toàn

Q: Làm sao quay lại dùng gói Claude Pro hoặc Max sau khi dùng relay?

Trong CC Switch, bật provider Claude Official ở tab Claude Code. Provider này có khối env rỗng, nên hai biến ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN bị xóa khỏi settings.json. Mở terminal mới, chạy claude rồi gõ /status để xem tài khoản. Gõ /login nếu được yêu cầu. Nếu request vẫn đi tới relay, hãy tìm biến ANTHROPIC_* còn sót trong shell bằng env | grep ANTHROPIC.

Cài CC Switch v3.20.4 để Claude Code dùng key Z.ai, Kimi, DeepSeek hay relay mà không sửa JSON tay. Xem settings.json đổi gì và cách quay về gói chính chủ.

CC Switch là gì và nó làm gì với Claude Code

CC Switch là một ứng dụng desktop mã nguồn mở. Nó giúp Claude Code dùng key của nhà cung cấp khác mà bạn không phải tự sửa file JSON. Key đó có thể của Z.ai, Kimi hay DeepSeek, của một relay mua trong nước, hoặc là key Anthropic Console. Bạn dán key vào ứng dụng rồi bấm Enable. Ứng dụng sẽ ghi lại ~/.claude/settings.json thay bạn.

Hướng dẫn này dùng bản v3.20.4. Phần chính là so sánh file đó trước và sau khi đổi provider. Sau đó bài chỉ cách quay về đăng nhập bằng gói thuê bao chính chủ. Cuối cùng, bài cho biết key của bạn thực sự nằm ở đâu trên ổ đĩa.

CC Switch viết bằng Tauri 2, mã nguồn ở github.com/farion1231/cc-switch, giấy phép MIT. Ngoài Claude Code, nó còn quản lý Codex, OpenCode, Gemini CLI và một số công cụ khác. Bài này tập trung vào Claude Code. Phần cuối có ghi chú ngắn cho Codex và OpenCode.

CC Switch là công cụ của bên thứ ba, không phải sản phẩm của Anthropic. Bài này không nói rằng Anthropic chấp thuận công cụ này hay bất kỳ nhà cung cấp nào trong danh sách của nó. Bài này cũng không bàn chuyện key rẻ có đáng tiền hay không. Nếu bạn còn đang chọn giữa trả theo token và trả theo tháng, hãy đọc so sánh chi phí Claude API và gói thuê bao trước.

Ai nhận được prompt và file của bạn khi đổi endpoint

Hãy đọc phần này trước khi cài. Bạn trỏ Claude Code tới một endpoint nào thì người vận hành endpoint đó nhận được mọi prompt bạn gõ và mọi file agent đọc. Trong đó có cả file .env và output của mọi lệnh agent chạy. Lý do rất đơn giản. Mỗi request Claude Code gửi tới ANTHROPIC_BASE_URL chứa toàn bộ ngữ cảnh của phiên làm việc, và ngữ cảnh đó chứa nội dung các file đã đọc.

Chiều ngược lại cũng quan trọng. Câu trả lời của model được sinh ra ở endpoint, nên endpoint quyết định agent gọi công cụ nào, với tham số nào. Một endpoint độc hại có thể trả về một lệnh Bash bất kỳ. Nếu bạn đã cho agent chạy lệnh mà không cần hỏi lại, lệnh đó sẽ chạy thật trên máy bạn. Cơ chế này giống hệt prompt injection với coding agent. Điểm khác duy nhất là kẻ tấn công đứng ngay ở vị trí của model.

README của CC Switch có một danh sách dài các relay giảm giá. Đó là danh sách nhà tài trợ của dự án. Chúng tôi không kiểm tra và không xếp hạng dịch vụ nào trong đó. Việc một cái tên có trong README không cho bạn biết họ giữ log bao lâu, hay ai đọc được log đó.

Vài nguyên tắc thực tế trước khi dán key của relay vào bất cứ đâu:

Chỉ dùng relay cho mã nguồn mà bạn chấp nhận để người khác đọc. Với mã của khách hàng hoặc của công ty, hãy dùng key chính chủ.
Chạy agent trên một máy riêng biệt, ví dụ theo hướng dẫn chạy Claude Code an toàn trên VPS. Như vậy agent không thấy được thư mục cá nhân của bạn.
Không để secret thật trong thư mục dự án. Cách làm chi tiết có trong bài giữ secret ngoài tầm đọc của AI agent.
Tạo key riêng cho từng nhà cung cấp, và đặt hạn mức chi tiêu nếu nhà cung cấp cho phép. Khi đó, thu hồi một key không ảnh hưởng tới các key khác.

Nếu bạn vẫn phải làm việc trong một thư mục có .env, hãy chặn công cụ đọc file của Claude Code bằng quy tắc deny trong settings.json:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

Quy tắc này chặn công cụ Read. Nó không chặn được việc agent chạy cat .env qua Bash, nên đây chỉ là một lớp bảo vệ phụ. Cách chắc chắn nhất vẫn là không để secret thật ở đó.

Cài CC Switch v3.20.4 trên Windows

Tính đến ngày 01/10/2026, bản phát hành mới nhất trên GitHub là v3.20.4, gắn thẻ ngày 22/09/2026. Mọi tên file và tên preset trong bài đều theo bản này. Bản sau có thể đổi tên preset, nên hãy so với giao diện bạn đang thấy.

Mở trang https://github.com/farion1231/cc-switch/releases/tag/v3.20.4. Chỉ tải từ trang này. Bản đăng lại trong nhóm chat hay trên trang chia sẻ file có thể đã bị sửa.
Tải file CC-Switch-v3.20.4-Windows.msi. Nếu không muốn cài vào hệ thống, có bản CC-Switch-v3.20.4-Windows-Portable.zip.
Chạy file MSI và cài như một ứng dụng Windows bình thường.
Mở CC Switch từ Start menu.

Nếu bạn nâng cấp từ bản cũ, hãy đọc kỹ ghi chú phát hành. Bản v3.20.4 có một bước migration cơ sở dữ liệu (schema từ phiên bản 18 lên 19). Tác giả khuyên bạn sao lưu thủ công trước khi nâng cấp. Trong PowerShell:

Copy-Item -Recurse $HOME\.cc-switch $HOME\cc-switch-backup

Trên macOS, README khuyên cài qua Homebrew. Trên Arch Linux có gói trong AUR:

brew install --cask cc-switch
paru -S cc-switch-bin

Với các bản phân phối Linux khác, hãy tải gói phù hợp trên cùng trang phát hành. Trang này có các file .deb, .rpm và .AppImage, cho cả x86_64 lẫn arm64.

Lần mở đầu tiên, nếu ~/.claude/settings.json đã có sẵn, CC Switch nhập file đó thành một provider mặc định. Vì vậy cấu hình hiện tại của bạn không bị mất khi mở ứng dụng.

Chụp lại settings.json trước khi thêm provider

Phần quan trọng nhất của bài là so sánh file trước và sau khi đổi. Hãy lưu một bản sao của file trước khi bấm bất kỳ nút nào trong CC Switch.

Trên Windows, trong PowerShell:

Copy-Item $HOME\.claude\settings.json $HOME\settings.before.json

Trên macOS hoặc Linux:

cp ~/.claude/settings.json ~/settings.before.json

Nếu lệnh báo file không tồn tại, nghĩa là Claude Code của bạn chưa có cấu hình cấp người dùng. Khi đó, hãy tạo file settings.before.json chỉ chứa {} để làm mốc so sánh, rồi làm tiếp.

Thêm provider Z.ai và xem settings.json thay đổi gì

Trong CC Switch, chọn tab Claude Code, bấm nút thêm provider và chọn preset của Z.ai. Ở v3.20.4, preset này tên là Zhipu GLM en. Đừng nhầm với Zhipu GLM, preset dùng endpoint ở Trung Quốc. Dán key vào ô API key, lưu lại, rồi bấm Enable trên thẻ của provider đó.

Bây giờ hãy so sánh. Lệnh git diff --no-index so được hai file bất kỳ, kể cả khi chúng không nằm trong repo git. Trên macOS hoặc Linux:

git diff --no-index ~/settings.before.json ~/.claude/settings.json

Trong PowerShell, nếu máy đã cài Git:

git diff --no-index $HOME\settings.before.json $HOME\.claude\settings.json

Nếu máy Windows không có Git, hãy dùng lệnh có sẵn của PowerShell:

Compare-Object (Get-Content $HOME\settings.before.json) (Get-Content $HOME\.claude\settings.json)

Giả sử máy bạn đang dùng gói thuê bao và file chưa có khối env. Kết quả sẽ trông như dưới đây. Thứ tự các dòng và tên model trên máy bạn có thể khác:

 {
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "zai-xxxxxxxxxxxxxxxx",
+    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-5.1",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.1",
+    "ANTHROPIC_MODEL": "glm-5.1"
+  },
   "permissions": {

Đọc từng dòng:

ANTHROPIC_BASE_URL là endpoint. Mọi request của Claude Code sẽ đi tới địa chỉ này thay vì máy chủ của Anthropic.
ANTHROPIC_AUTH_TOKEN là key của bạn. Claude Code gửi nó trong header Authorization: Bearer. Key nằm nguyên văn trong file, không được mã hóa, vì Claude Code cần đọc được nó.
ANTHROPIC_MODEL là model mặc định của phiên làm việc.
Ba biến ANTHROPIC_DEFAULT_*_MODEL chuyển tên model mà Claude Code yêu cầu (Haiku, Sonnet, Opus) sang tên model mà nhà cung cấp hiểu.

README nói CC Switch chỉ thay bốn thứ: endpoint, key, tên model và giao thức API. Ba thứ đầu bạn thấy ngay trong diff. Thứ tư không có trong file, vì mã nguồn v3.20.4 xóa trường apiFormat trước khi ghi. Claude Code không hiểu trường này. CC Switch chỉ dùng nó để quyết định có cần chạy proxy cục bộ hay không. Phần sau sẽ giải thích chuyện này.

Diff còn giúp bạn kiểm chứng một chi tiết trong mã nguồn. CC Switch không sửa từng dòng của settings.json. Mỗi lần bạn bật một provider, nó ghi lại toàn bộ file từ hai phần. Phần thứ nhất là cấu hình kết nối của provider đó. Phần thứ hai là một đoạn "cấu hình chung" (common config), được tách ra từ file gốc của bạn. Đoạn này giữ các khóa không liên quan tới kết nối, như permissions hay hooks. Câu "chỉ đổi endpoint, key và model" chỉ đúng khi đoạn cấu hình chung đã giữ đủ các khóa của bạn. Diff là cách để biết chắc điều đó trên máy của bạn.

Nếu diff có dòng bắt đầu bằng - ở permissions, hooks hay enabledPlugins, nghĩa là lần ghi này đã làm mất các khóa đó. Hãy mở phần common config của Claude trong form chỉnh provider, thêm lại các khóa đó, rồi bấm Enable lần nữa. Vì CC Switch ghi lại toàn bộ file, sau khi dùng nó bạn nên sửa cấu hình qua ứng dụng. Một dòng bạn tự sửa trong settings.json có thể biến mất ở lần đổi provider tiếp theo. Hãy chạy lại diff sau mỗi lần đổi.

Khi nhà cung cấp không dùng giao thức Anthropic

Claude Code chỉ dùng một giao thức: Messages API của Anthropic. Z.ai, Kimi và DeepSeek đều có endpoint tương thích với giao thức này, nên CC Switch chỉ cần ghi URL và key vào file. Nhiều relay khác chỉ có endpoint theo kiểu OpenAI. Với các nhà cung cấp này, CC Switch chạy một proxy cục bộ để chuyển request qua lại giữa hai định dạng.

Theo README, khi dùng proxy cục bộ, settings.json chỉ chứa một địa chỉ cục bộ và một key giữ chỗ là PROXY_MANAGED. Key thật nằm trong cơ sở dữ liệu của CC Switch. Vì vậy CC Switch phải đang chạy thì Claude Code mới gọi được model. Nếu bạn đóng ứng dụng, không còn gì lắng nghe ở địa chỉ cục bộ đó, nên Claude Code báo lỗi kết nối.

Nếu bạn muốn mỗi loại tác vụ dùng một model riêng thay vì đổi model cho cả phiên, hãy đọc thêm về định tuyến nhiều model cho coding agent.

Làm sao biết Claude Code đã dùng provider mới

README nói Claude Code nhận cấu hình mới ngay lập tức, còn các công cụ khác phải khởi động lại terminal hoặc ứng dụng. Để chắc chắn, hãy mở một terminal mới, chạy claude, rồi gõ /status. Màn hình trạng thái cho biết phiên đang xác thực theo cách nào.

Tiếp theo, hãy xem shell có biến môi trường nào xung đột với CC Switch không:

env | grep ANTHROPIC

Trong PowerShell:

Get-ChildItem Env:ANTHROPIC*

Lệnh này không nên in ra gì cả. CC Switch chỉ sửa settings.json. Nếu bạn thấy ANTHROPIC_API_KEY hay ANTHROPIC_BASE_URL ở đây, biến đó đến từ .bashrc, .zshrc hoặc từ biến môi trường của Windows. CC Switch không tạo ra nó. Mã nguồn CC Switch có một bộ kiểm tra riêng cho đúng những chỗ này: các file cấu hình shell và registry HKEY_CURRENT_USER\Environment. Lý do là một biến còn sót lại sẽ khiến bạn không biết chắc request đang đi đâu. Hãy xóa biến đó, mở terminal mới, rồi chạy lại lệnh.

Bằng chứng cuối cùng nằm ở phía nhà cung cấp. Gửi một prompt ngắn trong Claude Code, rồi mở trang thống kê sử dụng của nhà cung cấp. Request bạn vừa gửi phải xuất hiện ở đó. Đây là phép thử đáng tin nhất, vì nó được đo ngay tại máy chủ nhận request.

Quay về đăng nhập gói thuê bao chính chủ

Mỗi công cụ trong CC Switch có sẵn một provider chính chủ. Với Claude Code, provider đó tên là Claude Official, và cấu hình của nó có khối env rỗng. Bấm Enable để bật nó, rồi so lại với file gốc:

git diff --no-index ~/settings.before.json ~/.claude/settings.json

Nếu đúng, file sẽ không còn dòng nào chứa ANTHROPIC_BASE_URL hay ANTHROPIC_AUTH_TOKEN. Nếu vẫn còn khối env, khối đó phải rỗng hoặc không có biến ANTHROPIC_* nào.

Mở terminal mới, chạy claude và gõ /status. Bạn sẽ thấy tài khoản Claude của mình. Claude Code lưu thông tin đăng nhập ở một chỗ riêng, không phải trong settings.json, nên CC Switch không đụng tới nó. Nếu Claude Code yêu cầu đăng nhập, hãy gõ /login và làm theo các bước đăng nhập bình thường. Bài đăng nhập gói thuê bao hay dùng API key cho Claude Code giải thích sự khác nhau giữa hai cách xác thực này.

Đã quay về Claude Official mà nhà cung cấp cũ vẫn ghi nhận request thì nguyên nhân gần như luôn là một biến ANTHROPIC_* trong shell. Hãy chạy lại env | grep ANTHROPIC để tìm nó.

Với key Anthropic Console, hãy thêm một provider tùy chỉnh có endpoint là https://api.anthropic.com, rồi dán key vào. Sau đó bật provider và chạy diff giống như với Z.ai.

CC Switch lưu key ở đâu, và key có được mã hóa không

Theo README, dữ liệu nằm trong thư mục ~/.cc-switch/, trong một cơ sở dữ liệu SQLite tên là cc-switch.db. Trên Windows, đường dẫn là %USERPROFILE%\.cc-switch\cc-switch.db.

Đây là những gì chúng tôi tìm thấy khi đọc mã nguồn v3.20.4. Bảng providers có một cột settings_config kiểu TEXT. Cột này giữ cấu hình JSON của từng provider, trong đó có khối env chứa key. File Cargo.toml khai báo thư viện rusqlite với các tính năng bundled, backup và hooks, không có SQLCipher. Trong danh sách phụ thuộc, chúng tôi cũng không thấy thư viện mã hóa hay thư viện keychain nào. Kết luận: ở bản này, chúng tôi không tìm thấy lớp mã hóa nào cho key. Ai đọc được file cc-switch.db thì đọc được key.

Bạn có thể tự kiểm tra trên máy mình. macOS có sẵn sqlite3. Trên Ubuntu, cài bằng sudo apt install sqlite3. Trên Windows, tải bộ sqlite-tools từ trang sqlite.org.

sqlite3 ~/.cc-switch/cc-switch.db "SELECT app_type, name, substr(settings_config, 1, 160) FROM providers;"

Nếu cột thứ ba hiện nguyên văn key của bạn, nghĩa là key đang được lưu ở dạng văn bản thường (plaintext). Đừng chụp màn hình kết quả này để gửi vào nhóm hỗ trợ.

Cần đánh giá chuyện này cho đúng mức. Key đang dùng vốn đã nằm ở dạng plaintext trong ~/.claude/settings.json, vì Claude Code đọc nó từ đó. Dù cơ sở dữ liệu có được mã hóa thì key đó vẫn không được bảo vệ. Điểm khác là CC Switch giữ mọi key bạn từng thêm, chứ không riêng key đang dùng. Ngoài ra nó còn tạo thêm các bản sao:

Thư mục ~/.cc-switch/backups nhận một bản sao lưu tự động mỗi 24 giờ. Theo README, thư mục này giữ 10 bản gần nhất.
Nếu bạn bật đồng bộ qua WebDAV hoặc S3, cấu hình sẽ được đẩy lên kho lưu trữ đó. Ai vào được kho đó thì có key của bạn.

Vì vậy, hãy đối xử với thư mục ~/.cc-switch như một file chứa mật khẩu. Trên macOS và Linux, chỉ cho phép chính bạn đọc thư mục này bằng lệnh chmod 700 ~/.cc-switch. Khi gỡ ứng dụng hoặc bán máy, hãy kiểm tra xem thư mục đó còn không. Đồng thời thu hồi key trên trang quản lý của từng nhà cung cấp.

Ghi chú cho Codex và OpenCode

Quy trình giống với Claude Code: chọn tab của công cụ, rồi thêm và bật provider như trên. Khác biệt nằm ở file bị ghi. Codex dùng thư mục ~/.codex/, còn OpenCode dùng thư mục cấu hình riêng của nó. Hãy chụp lại các file trong thư mục đó trước khi bật provider, rồi chạy git diff --no-index như trên. Theo README, hai công cụ này phải khởi động lại terminal hoặc ứng dụng thì mới nhận cấu hình mới. Rủi ro bảo mật vẫn như cũ: endpoint nhận mọi thứ agent đọc.

Lỗi thường gặp sau khi đổi provider

Claude Code báo Invalid API key, hoặc báo lỗi bắt đầu bằng API Error: 401. Nhà cung cấp đã từ chối key. Có bốn nguyên nhân thường gặp. Key bị dán thiếu ký tự. Key của nhà cung cấp này bị dán vào provider của nhà cung cấp khác. Key đã bị thu hồi. Hoặc relay đọc key ở một header khác. ANTHROPIC_AUTH_TOKEN gửi key trong header Authorization, còn ANTHROPIC_API_KEY gửi key trong header x-api-key. Relay chỉ đọc một trong hai header thì sẽ từ chối header kia. Bài sửa lỗi Invalid API key trong Claude Code đi qua từng trường hợp.

Lỗi API 400 hoặc 404 có nhắc tới tên model. Endpoint không phục vụ model có tên trong ANTHROPIC_MODEL hoặc trong một biến ANTHROPIC_DEFAULT_*_MODEL. Tên model trong preset có thể đã cũ so với danh sách hiện tại của nhà cung cấp. Hãy lấy tên đúng từ tài liệu của nhà cung cấp, sửa lại trong CC Switch, rồi bật lại provider.

Lỗi quá tải xuất hiện liên tục. Hoặc relay đang chuyển tiếp lỗi quá tải từ dịch vụ phía sau nó, hoặc chính relay đã hết công suất. Đọc lỗi model overloaded trong Claude Code để phân biệt hai trường hợp này.

Lỗi kết nối, và settings.json chứa PROXY_MANAGED. Provider này cần proxy cục bộ của CC Switch, nhưng ứng dụng đang đóng. Hãy mở CC Switch rồi thử lại.

FAQ

CC Switch có làm mất plugin và hooks của Claude Code không?

README nói CC Switch chỉ thay endpoint, key, tên model và giao thức API. Trong mã nguồn v3.20.4, mỗi lần đổi provider, CC Switch ghi lại toàn bộ ~/.claude/settings.json. Nội dung mới gồm cấu hình của provider cộng với một đoạn cấu hình chung được tách ra từ file gốc. Các khóa như hooks hay permissions chỉ được giữ lại khi đoạn cấu hình chung có chứa chúng. Hãy lưu một bản sao của file trước khi bật provider, rồi chạy git diff --no-index để kiểm tra trên máy của bạn.

Key API trong CC Switch có được mã hóa không?

Ở bản v3.20.4, chúng tôi không tìm thấy lớp mã hóa nào. Key nằm trong cột settings_config của bảng providers, trong file SQLite ~/.cc-switch/cc-switch.db. Danh sách phụ thuộc không có SQLCipher hay thư viện keychain nào. Hãy chạy sqlite3 trên file đó để tự xem. Key đang dùng cũng nằm ở dạng plaintext trong ~/.claude/settings.json, vì Claude Code đọc nó từ đó.

Làm sao quay lại dùng gói Claude Pro hoặc Max sau khi dùng relay?

Trong CC Switch, bật provider Claude Official ở tab Claude Code. Provider này có khối env rỗng, nên hai biến ANTHROPIC_BASE_URL và ANTHROPIC_AUTH_TOKEN bị xóa khỏi settings.json. Mở terminal mới, chạy claude rồi gõ /status để xem tài khoản. Gõ /login nếu được yêu cầu. Nếu request vẫn đi tới relay, hãy tìm biến ANTHROPIC_* còn sót trong shell bằng env | grep ANTHROPIC.

Dùng relay với Claude Code có an toàn cho mã nguồn công ty không?

Người vận hành relay nhận được mọi prompt và mọi file Claude Code đọc, kể cả .env nếu agent mở file đó. Họ cũng tạo ra câu trả lời của model, nên họ có thể khiến agent chạy lệnh trên máy bạn. Với mã nguồn bạn không được phép chia sẻ, đừng dùng relay. Hãy dùng key chính chủ hoặc gói thuê bao chính chủ.

#claude-code#cc-switch#api-providers#coding-agents #bảo mật