Hướng dẫn sử dụng CC-Switch-CLI
CC-Switch-CLI là công cụ chuyển đổi provider (nhà cung cấp) dành cho dòng lệnh, phù hợp với máy chủ không có giao diện đồ họa, môi trường SSH, hoặc những ai cần chuyển đổi nhanh provider giữa Claude Code, Codex, Gemini CLI, OpenCode và OpenClaw.
Phù hợp với ai
Nếu bạn là người dùng máy tính để bàn thông thường, hãy ưu tiên sử dụng giao diện đồ họa CC Switch; nếu bạn đã quen thuộc với terminal hoặc cần quản lý cấu hình hàng loạt, hãy theo dõi trang này. Các khối mã dưới đây chỉ chứa lệnh, phần giải thích được đặt bên ngoài khối mã để tránh việc sao chép nhầm giải thích cùng với lệnh.
Cài đặt và Khởi chạy
Người dùng macOS / Linux có thể làm theo tài liệu chính thức để sử dụng tập lệnh cài đặt hoặc gói Releases; người dùng Windows nên tải gói nén tương ứng từ Releases và chạy trong thư mục chương trình sau khi giải nén.
curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash cc-switch.\cc-switch.exeNhập trực tiếp cc-switch bạn sẽ vào giao diện tương tác, phù hợp cho người mới bắt đầu xem menu trước; các lệnh dưới đây phù hợp khi bạn đã biết rõ mình muốn làm gì và muốn thực thi trực tiếp.
Kiểm tra môi trường
| Nội dung cần xác nhận | Cách kiểm tra | Lý do |
|---|---|---|
| Đã cài đặt CC Switch hoặc phiên bản CLI | Terminal hiện tại nhận diện được lệnh tương ứng | Mọi lệnh cấu hình đều sẽ thất bại nếu chưa được cài đặt. |
| Target CLI đã được cài đặt | Claude Code, Codex và Gemini CLI ít nhất có thể khởi động riêng lẻ | CC-Switch-CLI không tự động cài đặt công cụ mục tiêu cho bạn |
| Thông tin provider đầy đủ | Chuẩn bị Base URL, API Key và tên model | Cấu hình dòng lệnh không có nhắc nhở trực quan bằng đồ họa, thiếu một mục rất dễ dẫn đến thất bại. |
| Xác minh trước trong thư mục thử nghiệm | Không chuyển đổi hàng loạt trực tiếp trong các dự án thực tế | Dễ dàng hoàn tác hơn khi cấu hình không chính xác |
cc-switch env tools cc-switch env check cc-switch provider current cc-switch --app codex provider currentCác lệnh Provider
Provider là một mục cấu hình nhà cung cấp. Trước khi thêm Provider, trước tiên hãy chuẩn bị Base URL, API Key và tên model từ trang quản trị của nhà cung cấp; khi chỉnh sửa hoặc chuyển đổi, trước tiên hãy xác nhận số thứ tự (ID) bằng lệnh danh sách.
cc-switch provider list cc-switch provider add cc-switch provider edit <id> cc-switch provider fetch-models <id>cc-switch provider switch <id> cc-switch provider stream-check <id> cc-switch provider fetch-models <id>< id> cần được thay thế bằng con số hiển thị trong lệnh cc-switch provider list. Đừng sao chép nguyên văn < id> để thực thi.Quản lý theo Ứng dụng
Nếu bạn chỉ muốn xem cấu hình của một công cụ mục tiêu cụ thể, bạn có thể thêm --app. Điều này rất hữu ích để xử lý sự cố riêng biệt cho Claude Code, Codex và Gemini CLI.
cc-switch --app claude provider list cc-switch --app codex provider list cc-switch --app gemini provider list cc-switch --app opencode provider list cc-switch --app openclaw provider listcc-switch --app claude provider current cc-switch --app codex provider current cc-switch --app gemini provider currentSau khi xác nhận ứng dụng mục tiêu và provider hiện tại đều ổn, hãy tiến hành chuyển đổi. Khi chuyển đổi hoàn tất, hãy khởi động lại terminal, sau đó dùng công cụ mục tiêu gửi câu hỏi kiểm tra ngắn nhất.
claude "Please reply only: Claude Code is active" codex "Please reply only: Codex is active" gemini "Please reply only: Gemini is active"Đồng bộ hóa MCP
MCP không cần thiết đối với mọi người mới bắt đầu. Bạn chỉ cần xử lý khi đã sử dụng MCP trong Claude Code, Codex, Gemini CLI và cần đồng bộ hóa giữa các công cụ. Lần đầu tiên, bạn nên vào menu TUI trước để kiểm tra khu vực MCP, và không nên sao chép trực tiếp các lệnh nâng cao từ các bài hướng dẫn cũ.
cc-switch cc-switch --app codexQuy trình cấu hình
- Trước tiên hãy xác nhận công cụ mục tiêu bạn muốn chuyển đổi: Claude Code, Codex, Gemini CLI hoặc CLI khác.
- Chuẩn bị Base URL, API Key và tên model từ trang quản trị của provider.
- Thêm hoặc chọn Provider trong CC-Switch-CLI.
- Áp dụng Provider cho công cụ mục tiêu.
- Sau khi mở lại terminal, hãy kiểm tra bằng một câu hỏi ngắn nhất trên CLI mục tiêu.
- Sau khi xác nhận thành công, hãy áp dụng cùng Provider đó cho các công cụ mục tiêu khác.
| Kịch bản | Khuyến nghị |
|---|---|
| Sử dụng máy tính để bàn cục bộ | Ưu tiên sử dụng giao diện đồ họa CC Switch; các trường và trạng thái trực quan hơn |
| Máy chủ từ xa / SSH | Nên dùng CC-Switch-CLI; kiểm tra các lệnh của phiên bản hiện tại trước khi thao tác |
| Chuyển đổi cấu hình hàng loạt | Xác minh thành công trong một dự án thử nghiệm trước, sau đó áp dụng vào các dự án thực tế |
| Nhiều người dùng chung một máy | Không ghi Key của bạn vào cấu hình chung công khai; hãy xác nhận phạm vi hiệu lực của tệp cấu hình trước |
Khắc phục sự cố cho người mới bắt đầu
| Hiện tượng | Kiểm tra ưu tiên | Giải pháp |
|---|---|---|
| Command not found (Không tìm thấy lệnh) | Kiểm tra xem đã cài đặt chưa và đã được thêm vào PATH hay chưa | Mở lại terminal, hoặc quay lại hướng dẫn cài đặt chính thức để xác nhận vị trí cài đặt |
| Công cụ mục tiêu không thay đổi sau khi chuyển đổi | Đã mở lại terminal chưa và đã chọn đúng công cụ mục tiêu chưa | Đóng cửa sổ terminal hiện tại và mở lại, sau đó thử lại |
| 401 / Unauthorized (Không được phép) | Key có đầy đủ không và đã hết hạn chưa | Sao chép lại Key, đảm bảo không có khoảng trắng thừa |
| model not found (Không tìm thấy model) | Tên model đã được sao chép chính xác từ trang quản trị chưa | Điền lại theo danh sách model của nhà cung cấp |