Tool Integrations22 tháng 6, 2026Big Y

Thiết lập CC Switch Claude Code với Flatkey và NewAPI

Thiết lập định tuyến CC Switch Claude Code với Flatkey và NewAPI: chọn ứng dụng, trường khóa, base URL, lấy model, kiểm tra usage-log và xử lý sự cố.

Nếu bạn đang tìm kiếm CC Switch Claude Code, có lẽ bạn đã cài đặt trợ lý lập trình rồi. Vấn đề thiết lập hẹp hơn: bạn cần CC Switch ghi đúng cấu hình nhà cung cấp Claude Code, dùng đúng khóa Flatkey, trỏ đến đúng base URL, chọn các mô hình mà khóa của bạn thực sự có thể truy cập, và xác minh yêu cầu trong nhật ký sử dụng.

Hướng dẫn này bao gồm lộ trình thực tế cho việc định tuyến CC Switch Claude Code với Flatkey và quy trình một chạm kiểu NewAPI. Tài liệu CC Switch hiện tại của NewAPI mô tả một liên kết sâu ccswitch:// nhập từ trang mã token New API. Người dùng Flatkey có thể dùng cùng bề mặt cấu hình CC Switch đó theo cách thủ công: thêm nhà cung cấp Claude Code, dán khóa API Flatkey, đặt base URL cổng Claude Code, lấy các mô hình, lưu hồ sơ và xác minh tuyến.

Hướng dẫn này chỉ dùng văn bản. Nó không sử dụng ảnh chụp màn hình ứng dụng vì luồng giao diện CC Switch và Flatkey hiện tại cần được xem xét lại bằng ảnh chụp trước khi xuất bản các hình ảnh từng bước.

Trả lời nhanh: Cài đặt CC Switch Claude Code cho Flatkey

Đối với một thiết lập CC Switch Claude Code dùng Flatkey làm backend, hãy tạo một provider Claude Code trong CC Switch và dùng Flatkey router làm cổng gateway. Với các yêu cầu kiểu Anthropic Messages của Claude Code, hãy dùng URL gateway gốc, không phải đường dẫn OpenAI chat-completions.

Trường hoặc cấu hình CC Switch	Giá trị Flatkey	Cần xác minh gì
Ứng dụng	`Claude` hoặc `Claude Code`	Không cấu hình ứng dụng Codex hoặc Gemini khi mục tiêu là Claude Code.
Tab provider	`App-specific Provider` cho Claude Code, hoặc `Universal Provider` nếu bạn cũng đồng bộ Codex/Gemini	Provider chung cần kiểm tra sau khi đồng bộ vì mỗi ứng dụng có thể kỳ vọng một dạng URL khác nhau.
Tên	`Flatkey Claude Code`	Đặt tên rõ ràng để dễ nhận biết khi chuyển đổi trong khay CC Switch sau này.
API Key	Khóa API Flatkey của bạn	Tạo hoặc sao chép từ bảng điều khiển Flatkey. Đừng bao giờ dán khóa thật vào tài liệu chia sẻ.
Claude Code base URL	`https://router.flatkey.ai`	Dùng cho `ANTHROPIC_BASE_URL`. Claude Code sau đó sẽ truy cập các đường dẫn như `/v1/messages`.
OpenAI-compatible base URL	`https://router.flatkey.ai/v1`	Dùng cho các client tương thích OpenAI và kiểm tra fetch model gọi đến `/v1/models`.
Main/Sonnet/Opus/Haiku models	ID model từ kết quả fetch của CC Switch, bảng điều khiển Flatkey, hoặc danh mục giá	Dùng đúng ID model. Không dùng tên marketing hoặc nhãn theo họ model.
Xác minh	Chạy một prompt Claude Code ngắn và xem nhật ký sử dụng Flatkey	Thiết lập chưa hoàn tất cho đến khi yêu cầu xuất hiện trong bảng điều khiển Flatkey.

Nếu biểu mẫu CC Switch của bạn có trình chỉnh sửa JSON nâng cao, profile Claude Code nên có dạng như sau. Hãy dùng placeholder trong tài liệu; không bao giờ lưu khóa thật trong repo.

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-fk-your-flatkey-key",
    "ANTHROPIC_BASE_URL": "https://router.flatkey.ai",
    "ANTHROPIC_MODEL": "your-claude-model-id"
  }
}

Claude Code cũng hỗ trợ ANTHROPIC_API_KEY. Chỉ dùng một biến xác thực, không dùng cả hai, trừ khi bạn thực sự hiểu rõ thứ tự ưu tiên. Với routing qua gateway kiểu bearer, ANTHROPIC_AUTH_TOKEN giúp việc ánh xạ rõ ràng vì Claude Code sẽ gửi nó làm giá trị của header Authorization.

Vị trí của NewAPI trong quy trình CC Switch

Tài liệu CC Switch hiện tại của NewAPI cho biết bảng điều khiển New API có thể thêm lối tắt Chat Settings với JSON này:

{ "CC Switch": "ccswitch" }

Sau đó, trang quản lý token của New API có thể hiển thị tùy chọn CC Switch, tùy chọn này khởi chạy CC Switch thông qua liên kết sâu ccswitch:// và mở hộp thoại nhập nhà cung cấp. Tài liệu của NewAPI mô tả các trường của hộp thoại là loại ứng dụng, tên, mô hình chính, và các lựa chọn mô hình Haiku/Sonnet/Opus.

Đối với Flatkey, hãy dùng cùng khái niệm nhưng không khẳng định có nhập từ trang token của NewAPI. Nếu khóa của bạn là khóa Flatkey, hãy thêm nhà cung cấp trực tiếp trong CC Switch. Nếu khóa của bạn nằm trong một triển khai NewAPI, hãy dùng chức năng nhập một chạm của NewAPI. Điểm khác biệt quan trọng rất đơn giản: CC Switch quản lý cấu hình Claude Code cục bộ, còn Flatkey hoặc NewAPI xử lý lớp định tuyến upstream.

Trước khi bắt đầu

Trước khi thay đổi nhà cung cấp CC Switch Claude Code, hãy xác nhận các điều kiện tiên quyết sau:

CC Switch đã được cài đặt trên máy nơi Claude Code chạy.
Claude Code đã được cài đặt và có thể mở bình thường.
Bạn có thể đăng nhập vào Flatkey và mở bảng điều khiển.
Bạn có một khóa API Flatkey cho máy trạm hoặc nhà phát triển này.
Bạn biết ít nhất một ID mô hình Claude có sẵn cho tài khoản Flatkey của bạn.
Bạn có thể xem lại nhật ký sử dụng Flatkey sau yêu cầu kiểm tra đầu tiên.

Không sử dụng khóa sản xuất dùng chung cho lần kiểm tra đầu tiên. Hãy tạo một khóa giới hạn, đặt tên theo công cụ và chủ sở hữu, chẳng hạn như cc-switch-lee hoặc claude-code-devbox. Điều đó giúp lần kiểm tra khói đầu tiên của CC Switch Claude Code dễ kiểm tra và dễ thu hồi hơn.

Bước 1: Tạo Hoặc Sao Chép Một Khóa API Flatkey

Mở bảng điều khiển Flatkey và tạo một khóa để sử dụng Claude Code thông qua CC Switch. Sao chép nó một lần và lưu vào trình quản lý mật khẩu hoặc trình quản lý bí mật của nhóm bạn.

Trường CC Switch API Key nên chứa khóa Flatkey. Đừng dán khóa của Anthropic, OpenAI, Google hoặc khóa dành riêng cho nhà cung cấp vào hồ sơ này, trừ khi bạn đang cố ý cấu hình trực tiếp nhà cung cấp đó thay vì Flatkey.

Đối với nhóm, hãy tạo các khóa riêng theo người dùng, thiết bị hoặc môi trường. Một khóa dùng chung có thể hoạt động về mặt kỹ thuật, nhưng sau này sẽ khiến việc rà soát mức sử dụng và thu hồi khó khăn hơn.

Bước 2: Thêm một nhà cung cấp Claude Code trong CC Switch

Mở CC Switch và đi đến khu vực nhà cung cấp Claude Code. Sổ tay hướng dẫn người dùng CC Switch mô tả hai cách thêm: các nhà cung cấp riêng cho từng ứng dụng dành cho ứng dụng đã chọn, và Universal Provider cho cấu hình dùng chung giữa Claude Code, Codex, và Gemini.

Đối với thiết lập Flatkey CC Switch Claude Code đầu tiên, hãy bắt đầu với một nhà cung cấp Claude Code riêng cho ứng dụng:

Mở CC Switch.
Chọn Claude hoặc Claude Code trong bộ chuyển đổi ứng dụng.
Nhấp vào nút + để thêm nhà cung cấp.
Chọn đường dẫn nhà cung cấp tùy chỉnh nếu không có preset Flatkey.
Đặt tên nhà cung cấp thành Flatkey Claude Code.
Dán khóa API Flatkey của bạn.
Đặt base URL của gateway Claude Code thành https://router.flatkey.ai.
Chỉ chọn các mã model cho Main, Sonnet, Opus, và Haiku sau khi xác nhận chúng có sẵn cho tài khoản của bạn.

Nếu bạn dùng Universal Provider, hãy điền Name, API Key, và Endpoint URL, rồi chọn các ứng dụng bạn muốn đồng bộ. Sau khi đồng bộ, hãy kiểm tra cấu hình Claude Code được tạo ra. Với Claude Code, base đang hoạt động phải là https://router.flatkey.ai. Với các cấu hình ứng dụng tương thích OpenAI, https://router.flatkey.ai/v1 thường là base URL được mong đợi.

Bước 3: Tìm nạp Mô hình Trước khi Chọn Main, Sonnet, Opus và Haiku

CC Switch tài liệu hóa một hành động Fetch Models bên cạnh các đầu vào mô hình. Nó sử dụng khóa API đã cấu hình để gọi một endpoint tương thích với OpenAI /v1/models rồi cho phép bạn chọn các mã ID mô hình được trả về từ một danh sách thả xuống.

Trong bài viết này, một kiểm tra Flatkey có ngày vào 11 tháng 6, 2026 trả về HTTP 200 từ https://router.flatkey.ai/v1/models với phản hồi danh sách mô hình cho khóa kiểm thử đã cấu hình. Các ví dụ được trả về bao gồm các mã ID mô hình thuộc họ Claude như claude-sonnet-4-6, claude-sonnet-4-5, claude-opus-4-7, và claude-haiku-4-5. Hãy xem các ví dụ đó như một ảnh chụp hiện tại, không phải một khuyến nghị mô hình cố định.

Sử dụng quy tắc chọn mô hình này:

Main Model: chọn mô hình Claude mà bạn muốn Claude Code sử dụng theo mặc định.
Sonnet Model: chọn mô hình cân bằng mà nhóm của bạn mong đợi cho công việc lập trình hằng ngày.
Opus Model: chỉ chọn mô hình có năng lực cao hơn nếu ngân sách và quyền truy cập của bạn cho phép.
Haiku Model: chọn mô hình nhẹ cho các tác vụ nhanh hơn hoặc chạy nền nếu có sẵn.

Nếu Fetch Models thất bại, đừng đoán. Hãy mở bảng điều khiển Flatkey hoặc danh mục giá, sao chép một mã ID mô hình tương thích với Claude chính xác, và chỉ thử trước với mô hình đó.

Bước 4: Lưu, Đồng Bộ, Và Kiểm Tra Cấu Hình Claude Code Được Tạo Ra

Sau khi bạn lưu nhà cung cấp, CC Switch sẽ ghi cấu hình nhà cung cấp đang hoạt động cho Claude Code. Đường dẫn tệp chính xác có thể thay đổi tùy theo phiên bản CC Switch và phạm vi ứng dụng, nhưng tài liệu cài đặt chính thức của Claude Code xác nhận rằng các biến môi trường có thể được cấu hình thông qua settings.json dưới khóa env.

Kiểm tra rằng cấu hình được tạo ra không chứa các giá trị xác thực xung đột. Một hồ sơ Flatkey sạch nên có một trong các mẫu sau:

# Kiểu cổng vào token bearer
ANTHROPIC_AUTH_TOKEN=sk-fk-your-flatkey-key
ANTHROPIC_BASE_URL=https://router.flatkey.ai

hoặc:

# Kiểu API key
ANTHROPIC_API_KEY=sk-fk-your-flatkey-key
ANTHROPIC_BASE_URL=https://router.flatkey.ai

Đừng để một khóa Anthropic trực tiếp cũ vẫn còn hoạt động trong shell của bạn khi kiểm tra một hồ sơ CC Switch Claude Code mới. Nếu shell vẫn xuất ra một ANTHROPIC_API_KEY khác, việc khắc phục sự cố có thể khó hơn vì tiến trình đang chạy có thể không sử dụng hồ sơ CC Switch mà bạn nghĩ là nó đang sử dụng.

Bước 5: Xác minh trong Claude Code và nhật ký sử dụng Flatkey

Mở một terminal mới sau khi bật nhà cung cấp Flatkey trong CC Switch. Claude Code có thể hỗ trợ chuyển đổi nóng trong một số đường dẫn CC Switch, nhưng một terminal mới sẽ loại bỏ sự nhầm lẫn về trạng thái shell trong lần kiểm tra đầu tiên.

Khởi động Claude Code.
Kiểm tra mô hình hoặc trạng thái đang hoạt động trong Claude Code.
Gửi một prompt nhỏ, chẳng hạn yêu cầu nó trả lời bằng một câu ngắn.
Mở bảng điều khiển Flatkey.
Xem lại nhật ký sử dụng để kiểm tra thời điểm yêu cầu, ID mô hình và tên khóa.

Thiết lập CC Switch Claude Code chỉ hoàn tất khi cả ba lớp đều khớp: CC Switch hiển thị nhà cung cấp Flatkey là đang hoạt động, Claude Code sử dụng mô hình/base URL mong đợi, và nhật ký Flatkey cho thấy yêu cầu.

Khắc phục sự cố CC Switch Claude Code với Flatkey

Vấn đề	Nguyên nhân có thể	Cách khắc phục
Lỗi xác thực	Khóa sai, bị vô hiệu hóa, bị sao chép kèm khoảng trắng, hoặc không phải khóa Flatkey.	Tạo một khóa mới trong Flatkey, dán lại và xác minh rằng bạn đang dùng `ANTHROPIC_AUTH_TOKEN` hoặc `ANTHROPIC_API_KEY`, không phải các giá trị xung đột.
404 hoặc sai đường dẫn endpoint	URL bao gồm dạng đường dẫn không đúng cho Claude Code.	Với Claude Code, dùng `https://router.flatkey.ai`. Với việc fetch mô hình tương thích OpenAI hoặc các client khác, dùng `https://router.flatkey.ai/v1`.
Fetch Models thất bại	Khóa không thể gọi `/v1/models`, base URL sai, hoặc endpoint tạm thời không khả dụng.	Dùng `https://router.flatkey.ai/v1` cho đường dẫn fetch mô hình, sau đó quay về các model ID chính xác từ bảng điều khiển Flatkey.
Claude Code vẫn dùng nhà cung cấp cũ	Một tiến trình terminal cũ hoặc biến môi trường shell đang ghi đè lên profile CC Switch.	Mở một terminal mới, kiểm tra các biến môi trường shell và đảm bảo nhà cung cấp Flatkey đã được bật trong CC Switch.
Chọn mô hình được nhưng yêu cầu vẫn thất bại	Mô hình đã chọn có trong danh sách nhưng không khả dụng với khóa, nhóm, số dư hoặc chính sách tài khoản hiện tại của bạn.	Trước tiên hãy thử một mô hình đã biết là có quyền truy cập. Xem lại quyền truy cập tài khoản Flatkey, số dư, hạn mức và nhật ký sử dụng.
Tìm kiếm công cụ MCP làm thay đổi hành vi	Claude Code xem các base URL không phải của bên thứ nhất như định tuyến qua gateway.	Hãy làm theo hướng dẫn về gateway của Claude Code trước khi bật hành vi tìm kiếm công cụ nâng cao thông qua proxy. Đừng bật các cờ dành riêng cho gateway trừ khi gateway của bạn chuyển tiếp các khối bắt buộc.

Phần lớn các lỗi CC Switch Claude Code đều xoay quanh bốn trường: khóa, base URL, model ID và profile đang hoạt động. Hãy kiểm tra những thứ đó trước khi xây dựng lại toàn bộ cơ sở dữ liệu CC Switch.

CC Switch Vs A Claude Code Router

CC Switch và một Claude Code router giải quyết các phần khác nhau của quy trình làm việc. CC Switch là trình quản lý cấu hình cục bộ. Flatkey là lớp định tuyến và truy cập.

Layer	What It Does	What It Does Not Do
CC Switch	Lưu trữ hồ sơ nhà cung cấp, chuyển đổi cấu hình Claude Code/Codex/Gemini, quản lý các trường model, và có thể nhập nhà cung cấp thông qua deep link.	Nó không phải là tài khoản model upstream, hệ thống thanh toán, hoặc router.
Claude Code	Chạy trợ lý lập trình và đọc các giá trị môi trường/cấu hình đang hoạt động.	Nó không tự quản lý các khóa đa nhà cung cấp của nhóm bạn hoặc thanh toán.
Flatkey	Cung cấp một khóa, các endpoint gateway, truy cập model, khả năng hiển thị mức sử dụng, định tuyến, và các kiểm soát thanh toán cho các model được hỗ trợ.	Nó không thay thế giao diện chuyển đổi hồ sơ cục bộ của CC Switch.

Nếu bạn chỉ cần một thiết lập gateway cố định, bạn có thể cấu hình Claude Code trực tiếp. Nếu bạn chuyển đổi giữa nhiều nhà cung cấp, máy trạm, hoặc các tầng model, quy trình làm việc CC Switch Claude Code sẽ mang lại cho bạn một bề mặt điều khiển gọn gàng hơn. Nếu bạn cũng đang di chuyển mã ứng dụng sang một gateway, hãy đọc hướng dẫn OpenAI-compatible API migration. Nếu bạn đang phân vân giữa một proxy chỉ dành cho Claude và một gateway rộng hơn, hãy đọc Claude API proxy vs router.

Khuyến nghị triển khai cho nhóm

Với một nhà phát triển, chỉ cần một khóa Flatkey và một nhà cung cấp CC Switch. Với một nhóm, hãy xem thiết lập CC Switch Claude Code như một triển khai kiểm soát truy cập quy mô nhỏ.

Tạo một khóa Flatkey có tên riêng cho từng nhà phát triển, máy trạm hoặc môi trường.
Ghi lại các mã model Claude đã được phê duyệt và mỗi mã được ánh xạ vào tầng nào trong CC Switch.
Hãy dùng hạn mức trước khi mời thêm người dùng vào cùng một thiết lập định tuyến.
Rà soát nhật ký sử dụng sau ngày đầu tiên, không chỉ sau một bất ngờ về hóa đơn.
Giữ ảnh chụp màn hình khỏi các tài liệu công khai cho đến khi giao diện hiện tại được người đánh giá xác nhận.
Chỉ dùng chức năng nhập một chạm của NewAPI cho các khóa được quản lý trong NewAPI; dùng thiết lập nhà cung cấp Flatkey thủ công cho các khóa Flatkey.

FAQ

Thiết lập CC Switch Claude Code là gì?

Một thiết lập CC Switch Claude Code là một hồ sơ nhà cung cấp trong CC Switch, ghi endpoint, khóa và các cài đặt model mà Claude Code nên dùng. Với Flatkey, hồ sơ đó trỏ Claude Code đến bộ định tuyến Flatkey và sử dụng khóa Flatkey.

URL gốc của Flatkey Claude Code có nên bao gồm `/v1` không?

Đối với ANTHROPIC_BASE_URL của Claude Code, hãy dùng https://router.flatkey.ai. Đối với các client ứng dụng tương thích OpenAI và các kiểm tra lấy model gọi trực tiếp /v1/models, hãy dùng https://router.flatkey.ai/v1.

Nhập một lần của NewAPI có tự động cấu hình Flatkey không?

Không. Luồng CC Switch một lần nhấp của NewAPI được tài liệu hóa cho trang quản lý token New API. Với Flatkey, hãy thêm nhà cung cấp thủ công trong CC Switch trừ khi sau này Flatkey phát hành một liên kết nhập chuyên dụng ccswitch://.

CC Switch có thể lấy model Flatkey không?

Có, khi khóa đã cấu hình có thể truy cập danh sách model tương thích OpenAI của Flatkey. Một kiểm tra ngày 11 tháng 6 năm 2026 cho bài viết này trả về HTTP 200 từ https://router.flatkey.ai/v1/models và phản hồi danh sách model cho khóa kiểm thử đã cấu hình.

Tôi nên dùng `ANTHROPIC_API_KEY` hay `ANTHROPIC_AUTH_TOKEN`?

Claude Code tài liệu hóa cả hai. ANTHROPIC_API_KEY được gửi dưới dạng header khóa API, còn ANTHROPIC_AUTH_TOKEN được gửi qua đường dẫn xác thực. Hãy dùng một cách rõ ràng cho hồ sơ Flatkey và tránh để cả hai cùng được đặt với các giá trị khác nhau.

Làm sao tôi biết thiết lập đã hoạt động?

Thiết lập đã hoạt động khi CC Switch hiển thị nhà cung cấp Flatkey là đang hoạt động, Claude Code dùng model mong đợi, một prompt kiểm thử nhỏ thành công và yêu cầu xuất hiện trong nhật ký sử dụng của Flatkey.