CC-Switch

CC-Switch là công cụ quản lý cấu hình cục bộ đa nền tảng, có thể lưu nhiều Provider cho các công cụ lập trình như Claude Code và Codex, rồi ghi cấu hình đang bật vào tệp cấu hình của công cụ tương ứng. Bạn có thể chuyển giữa AGTCloud và các cấu hình đã lưu khác mà không cần sửa tệp thủ công mỗi lần.

Hướng dẫn này chỉ trình bày Provider riêng cho Claude Code và Codex. Công cụ lập trình tương ứng gửi yêu cầu trực tiếp đến AGTCloud; không bật Local Proxy, Failover, chuyển đổi giao thức hoặc Universal Provider của CC-Switch.

Chuyển đổi sẽ sửa cấu hình công cụ trên máy cục bộ

CC-Switch cập nhật các tệp cấu hình đang được Claude Code hoặc Codex sử dụng. Trước lần dùng đầu tiên, xác nhận cấu hình hiện có được nhập đúng và xuất bản sao lưu trước khi thêm AGTCloud.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

Cài đặt và khởi chạy cơ bản Claude Code hoặc Codex;
Đăng ký và đăng nhập AGTCloud;
Tạo AGTCloud API Key trên trang API Keys;
Sao chép ID mô hình mà API Key hiện tại nhìn thấy và hỗ trợ giao thức của công cụ đích từ danh mục mô hình;
Chuẩn bị dự án thử nghiệm không chứa mã nhạy cảm hoặc thông tin xác thực của môi trường production.

Với Claude Code, chọn mô hình hỗ trợ Anthropic Messages; với Codex, chọn mô hình hỗ trợ OpenAI Responses. MODEL_ID là giá trị giữ chỗ cần thay thế, không phải tên mô hình thực tế.

Tải và cài đặt CC-Switch

Chỉ tải gói cài đặt từ trang web chính thức CC-Switch hoặc GitHub Releases. Trang web hoặc ứng dụng yêu cầu nạp tiền, thanh toán cho chính CC-Switch hay cung cấp thông tin đăng nhập đều không phải kênh chính thức.

Để cài đặt thông thường, chọn Windows MSI của phiên bản hiện tại trên GitHub Releases;
Nếu không muốn cài đặt, chọn Windows Portable ZIP;
Giải nén bản Portable rồi chạy CC-Switch.exe;
Nếu Windows chặn chạy, hãy kiểm tra nguồn tệp và chữ ký số trước, không tắt tính năng bảo mật hệ thống.

CC-Switch quản lý cấu hình, không thay thế Claude Code hoặc Codex. Trước tiên hãy đảm bảo công cụ lập trình đích khởi động bình thường.

Khởi chạy lần đầu và sao lưu

Kiểm tra kết quả nhập tự động

Khi khởi chạy lần đầu, CC-Switch thử nhập cấu hình Claude Code, Codex và các công cụ khác có sẵn trên máy. Mở từng trang ứng dụng và xác nhận cấu hình chính thức hoặc Provider tùy chỉnh hiện có đã xuất hiện trong danh sách.

Giữ Provider hiện có

Không xóa cấu hình chính thức được nhập tự động. Khi cần ngừng dùng AGTCloud, bạn có thể bật lại Provider đó để khôi phục cách kết nối ban đầu.

Xuất bản sao lưu dữ liệu

Vào Cài đặt → Nâng cao → Quản lý dữ liệu, dùng chức năng xuất của phiên bản hiện tại để lưu bản sao lưu. Tệp có thể chứa API Key và thông tin Provider nhạy cảm khác; lưu ở nơi tin cậy, không tải lên kho mã hoặc dịch vụ lưu trữ công khai.

Hướng dẫn này không yêu cầu sửa trực tiếp tệp cấu hình

CC-Switch ghi cấu hình cho công cụ tương ứng. Không ghi đè ~/.claude/settings.json, ~/.codex/auth.json hoặc ~/.codex/config.toml chỉ để áp dụng ví dụ của nền tảng khác.

Thêm AGTCloud Provider

Chọn ứng dụng cần cấu hình ở phía trên, nhấn nút thêm ở góc trên bên phải, rồi dùng cấu hình tùy chỉnh trong mục nhà cung cấp riêng cho ứng dụng. Claude Code và Codex dùng giao thức và Base URL khác nhau, vì vậy cần tạo Provider riêng.

Mở trang Claude Code Provider

Chọn Claude Code ở phía trên CC-Switch, nhấn thêm nhà cung cấp, rồi chọn mục tùy chỉnh hoặc mục Custom Provider tương ứng của phiên bản hiện tại.

Điền thông tin kết nối

Trường	Giá trị
`Provider Name`	`AGTCloud`
`Base URL`	`https://api.agtcloud.cn`
`API Key`	`your-api-key`
`Primary Model`	`MODEL_ID`
`Authentication`	Dùng API Key, không dùng `ANTHROPIC_AUTH_TOKEN`

Chỉ điền API Origin hiển thị trên trang này làm Base URL, không thêm /v1. Claude Code tự gửi yêu cầu đến /v1/messages.

Thiết lập ánh xạ mô hình

Nếu phiên bản hiện tại hiển thị ánh xạ vai trò Haiku, Sonnet và Opus, ban đầu bạn có thể ánh xạ cả ba vào cùng một MODEL_ID đã xác nhận hỗ trợ Anthropic Messages. Chỉ thiết lập mô hình riêng khi hiểu rõ khả năng thực tế của từng mô hình.

Lưu nhưng chưa bật proxy

Lưu Provider. Không bật Local Proxy, Failover, chuyển đổi giao thức hoặc tính năng định tuyến nâng cao khác.

Dùng xác thực API Key

Cấu hình Claude Code của AGTCloud dùng xác thực API Key tương ứng với ANTHROPIC_API_KEY. Không sao chép cấu hình dùng ANTHROPIC_AUTH_TOKEN hoặc Bearer Token của nền tảng khác.

Bật và kiểm tra cấu hình

Bật AGTCloud

Quay lại danh sách nhà cung cấp của ứng dụng tương ứng, nhấn nút bật trên thẻ AGTCloud. Xác nhận thẻ hiển thị trạng thái đang bật hoặc trạng thái tương đương của phiên bản hiện tại.

Tải lại công cụ đích

Claude Code thường phát hiện thay đổi cấu hình, nhưng nên mở phiên mới để kiểm tra;
Với Codex, cần đóng cửa sổ terminal hiện tại, mở lại terminal rồi khởi chạy Codex.

Không dùng phiên cũ đã gửi yêu cầu để đánh giá việc chuyển đổi có thành công hay không.

Kiểm tra cấu hình hiện tại

Trong công cụ đích, chạy:

/status

Kiểm tra Provider, Base URL, nguồn xác thực và ID mô hình. Claude Code không được có /v1 lặp; Base URL của Codex phải kết thúc bằng đúng một /v1.

Thử tác vụ chỉ đọc

Trong dự án thử nghiệm an toàn có README.md, nhập:

Hãy đọc README.md và tóm tắt mục đích dự án thành ba ý. Không sửa bất kỳ tệp nào.

Nếu kết quả được trả về bình thường và không có thay đổi trái phép, kết nối cơ bản đã được thiết lập. Bước này phát sinh mức sử dụng API thông thường.

Chuyển nhanh bằng khay hệ thống

CC-Switch cung cấp danh sách Provider riêng cho từng ứng dụng trong khay hệ thống. Nhấn chuột phải vào biểu tượng, mở menu con Claude hoặc Codex và chọn Provider cần bật.

Chuyển bằng khay chỉ là cách truy cập cấu hình khác, không yêu cầu bật Local Proxy. Sau khi chuyển Codex, vẫn cần mở lại terminal.

Quay lại cấu hình ban đầu

Mở trang Claude Code hoặc Codex trong CC-Switch;
Tìm Provider chính thức đã nhập khi khởi chạy lần đầu;
Nhấn nút bật;
Mở phiên Claude Code mới hoặc mở lại terminal Codex để xác nhận đã khôi phục.

Provider của Claude Code và Codex được cách ly với nhau. Chuyển Claude Code không tự sửa Codex và ngược lại.

Câu hỏi thường gặp

Hiện tượng	Kiểm tra trước	Cách xử lý
Không tìm thấy gói cài đặt phù hợp	Nguồn tải, hệ điều hành và kiến trúc bộ xử lý	Chỉ tải phiên bản hiện tại từ `ccswitch.io` hoặc GitHub Releases chính thức
Provider cũ không xuất hiện	Kết quả nhập lần đầu và đường dẫn cấu hình công cụ gốc	Xác nhận Claude Code hoặc Codex đã cài đặt và có cấu hình, rồi mở lại CC-Switch
Báo không thể ghi khi bật	Quyền và trạng thái sử dụng tệp cấu hình	Đóng công cụ đích đang chạy, kiểm tra quyền thư mục cấu hình người dùng rồi thử lại
Trả về `401`	Nội dung API Key và phương thức xác thực	Dùng API Key hợp lệ; không dùng `ANTHROPIC_AUTH_TOKEN` cho Claude Code
Trả về `403`	Trạng thái Key, quyền tài khoản và mô hình	Kiểm tra phạm vi sử dụng của API Key và mô hình trong bảng điều khiển
Trả về `404`	Base URL, `/v1` lặp, Endpoint đầy đủ và ID mô hình	Claude Code dùng `https://api.agtcloud.cn`; Codex dùng `https://api.agtcloud.cn/v1`, không điền đường dẫn yêu cầu đầy đủ
Không tải được danh sách mô hình	Hỗ trợ `/v1/models`, mạng và API Key	Sao chép ID mô hình đầy đủ mà Key hiện tại nhìn thấy từ danh mục mô hình rồi điền thủ công
Claude Code vẫn dùng cấu hình cũ	Trạng thái bật Provider và bộ nhớ đệm phiên cũ	Xác nhận thẻ AGTCloud đang bật, mở phiên Claude Code mới và chạy `/status`
Codex vẫn dùng cấu hình cũ	Terminal đã khởi động lại chưa	Đóng cửa sổ terminal hiện tại, mở lại rồi khởi chạy Codex
Trò chuyện thông thường thành công nhưng gọi công cụ thất bại	Giao thức và khả năng gọi công cụ của mô hình	Với Claude Code, chọn mô hình hỗ trợ Anthropic Messages và gọi công cụ; với Codex, chọn mô hình hỗ trợ Responses
Base URL thành `/v1/v1`	Loại ứng dụng và cách điền URL	Xóa `/v1` với Claude Code; chỉ giữ một `/v1` với Codex

Nếu chưa xác định được vấn đề, ghi lại công cụ đích, thời gian yêu cầu, API Base URL, ID mô hình, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi API Key đầy đủ hoặc bản sao lưu dữ liệu CC-Switch.

Khuyến nghị bảo mật

Không đưa API Key vào ảnh chụp màn hình, nhật ký, kho mã hoặc cấu hình dùng chung;
Bản xuất dữ liệu CC-Switch có thể chứa thông tin Provider nhạy cảm; bảo quản như bản sao lưu thông tin xác thực;
Chỉ cài CC-Switch từ kênh chính thức, không gửi thông tin đăng nhập nền tảng cho ứng dụng bên thứ ba;
Dùng dự án thử nghiệm an toàn cho lần kiểm tra đầu tiên và giữ phê duyệt thao tác của Claude Code, Codex ở trạng thái bật;
Nếu nghi API Key bị lộ, vô hiệu hóa hoặc xóa ngay trong bảng điều khiển, rồi tạo Key mới.