Cách dùng Claude Code với bất kỳ model nào: Thiết lập SKILL.md

Claude Code có thể trở nên hữu ích hơn nhiều khi nó biết lớp định tuyến AI của bạn hoạt động như thế nào. Thiết lập SKILL.md là cách gọn gàng để dạy nó quy trình đó: router của Flatkey nằm ở đâu, cách phát hiện các model ID đang hoạt động, cách gọi các model và công cụ được hỗ trợ, và những quy tắc an toàn nào cần tuân theo trước khi tiêu tiền hoặc chạm vào hệ thống production.

Có một lưu ý quan trọng ngay từ đầu. Vòng lặp suy luận riêng của Claude Code vẫn chạy trên Claude. Tài liệu gateway của Anthropic cho biết Claude Code có thể kết nối với một LLM gateway, nhưng không hỗ trợ chuyển hướng chính Claude Code tới các model không phải Claude thông qua gateway. Hãy dùng hướng dẫn này cho phiên bản thực tế của Cách dùng Claude Code với bất kỳ model nào: Thiết lập SKILL.md: giữ Claude Code làm tác nhân lập trình của bạn, rồi cấp cho nó một skill Flatkey để nó có thể khám phá và gọi bất kỳ model hoặc công cụ có tính phí nào được Flatkey hỗ trợ từ dự án của bạn khi nhiệm vụ yêu cầu.

SKILL.md công khai của Flatkey được xây dựng cho mục đích đó. Nó hướng dẫn các agent sử dụng https://router.flatkey.ai, base URL tương thích OpenAI https://router.flatkey.ai/v1, danh mục model trực tiếp, marketplace công cụ, các lệnh gọi nhỏ ban đầu, request ID, và các cổng phê duyệt cho việc ghi, gửi, mua, xóa, xuất bản hoặc thay đổi quyền.

Nếu bạn mới làm quen với chính router, hãy mở Flatkey API quickstart bên cạnh hướng dẫn này. Nếu bạn đang so sánh với quá trình chuyển đổi nhà cung cấp rộng hơn, các hướng dẫn OpenAI API alternative và unified AI API workflow giải thích chi tiết hơn về mẫu base URL.

Câu trả lời nhanh

Hãy dùng thiết lập này khi bạn muốn Claude Code vận hành Flatkey ngay trong repo của mình:

1. Tạo một Flatkey API key trong Flatkey Console.
2. Cài skill Flatkey vào Claude Code dưới dạng ~/.claude/skills/flatkey/SKILL.md hoặc .claude/skills/flatkey/SKILL.md.
3. Lưu FLATKEY_API_KEY trong shell hoặc local secret manager của bạn, không để trong file đã commit.
4. Yêu cầu Claude Code dùng skill Flatkey, lấy danh mục model trực tiếp, và chạy một lệnh kiểm tra nhỏ qua https://router.flatkey.ai/v1.
5. Kiểm tra Flatkey Usage Logs để xem model, số lượng token, độ trễ, trạng thái, và chi phí.

Nếu bạn muốn lưu lượng thuộc họ Claude của Claude Code đi qua Flatkey, hãy dùng hướng dẫn Claude Code của Flatkey thay vì base URL tương thích OpenAI /v1:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Đường dẫn đó dành cho định tuyến gateway của Claude Code. Đường dẫn SKILL.md là để dạy Claude Code cách sử dụng các model và công cụ Flatkey từ dự án.

SKILL.md thay đổi gì trong Claude Code

Một skill của Claude Code là một thư mục có file SKILL.md. Claude Code tải metadata của skill khi khởi động, rồi chỉ đọc phần nội dung skill khi nhiệm vụ khớp hoặc khi bạn gọi trực tiếp skill đó. Điều đó khiến một skill trở thành nơi phù hợp hơn CLAUDE.md cho các quy trình lặp lại như "khám phá các model Flatkey, chọn một route được hỗ trợ, chạy một lệnh gọi nhỏ, và xác minh Usage Logs."

Với Flatkey, skill nên khiến Claude Code thực hiện nhất quán năm việc sau:

Đó là cốt lõi thực tế của Cách dùng Claude Code với bất kỳ model nào: Thiết lập SKILL.md. Claude Code vẫn là bộ điều phối. Flatkey trở thành lớp model và công cụ mà nó có thể vận hành một cách có chủ đích.

Bước 1: Chọn cài đặt cá nhân hoặc theo dự án

Cài skill ở cấp toàn cục nếu bạn muốn nó khả dụng trong mọi repo:

mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

Cài nó bên trong một repo nếu bạn muốn cả team dùng chung cùng một quy trình làm việc Flatkey:

mkdir -p .claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o .claude/skills/flatkey/SKILL.md

Với skill dùng chung cho dự án, hãy rà soát file trước khi commit nó:

sed -n '1,200p' .claude/skills/flatkey/SKILL.md

Đừng biến lệnh cài đặt thành một shell script tự chạy. Skill là nội dung hướng dẫn. Hãy coi nó như việc thêm bất kỳ quy trình phát triển nào khác vào repo của bạn: lấy về, rà soát, rồi chỉ commit nếu cả team đồng ý.

Bước 2: Thiết lập khóa Flatkey một cách an toàn

Sử dụng biến môi trường:

export FLATKEY_API_KEY="sk-fk-your-key"

Nếu bạn cần biến này tồn tại lâu dài, hãy đặt nó trong shell profile, secret manager của bạn, hoặc một file môi trường cục bộ được git bỏ qua. Đừng đặt key trong .claude/settings.json, CLAUDE.md, một SKILL.md đã commit, hoặc một prompt bạn dán vào một thread dùng chung.

Quy tắc của chính skill Flatkey rất đơn giản: hãy dùng FLATKEY_API_KEY hiện có nếu nó đã được cấu hình, và không bao giờ in, ghi log, commit, hay gửi key đó đi đâu ngoài router.flatkey.ai hoặc Flatkey Console đã xác thực.

Bước 3: Xác nhận Claude Code nhìn thấy skill

Khởi động Claude Code từ repo hoặc terminal nơi skill khả dụng:

claude

Sau đó kiểm tra các skill khả dụng:

/skills

Bạn sẽ thấy flatkey trong danh sách skill. Nếu bạn đã cài skill trong khi một phiên Claude Code đang chạy mà nó không xuất hiện, hãy khởi động lại Claude Code. Claude Code có thể phát hiện nhiều chỉnh sửa skill trong suốt một phiên, nhưng việc khởi động lại là cách đơn giản nhất để loại bỏ sự mơ hồ trong quá trình thiết lập.

Bây giờ hãy yêu cầu một tác vụ đầu tiên vô hại:

Use the flatkey skill. Verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog from Flatkey, and summarize the first five text-capable model IDs you see. Do not run a generation yet.

Việc này kiểm tra khả năng phát hiện mà không tốn ngân sách sinh nội dung.

Bước 4: Lấy catalog model trực tiếp

Skill Flatkey yêu cầu Claude Code lấy catalog model trực tiếp trước khi chọn một model. Lệnh trực tiếp là:

curl -fsS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Trong một quy trình thực tế, hãy yêu cầu Claude Code chỉ chọn từ các ID trả về:

Use the flatkey skill. Fetch the live model catalog, choose one low-cost text model returned by the catalog for a one-sentence smoke test, and explain why you chose it before running the request.

Điều này tránh một lỗi phổ biến của agent: dùng tên model từ trí nhớ hoặc từ một bài viết cũ. Catalog là nguồn sự thật về những gì khóa của bạn có thể gọi tại thời điểm đó.

Bước 5: Chạy một lệnh kiểm tra nhỏ tương thích với OpenAI

Sau khi catalog trả về, hãy chạy một request nhỏ qua API tương thích OpenAI của Flatkey:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-a-model-id-from-the-live-catalog",
    "messages": [
      {
        "role": "user",
        "content": "Reply with one sentence: Flatkey smoke test passed."
      }
    ],
    "max_tokens": 40
  }'

Hãy giữ lệnh gọi đầu tiên thật đơn giản. Bạn đang kiểm tra xác thực, ID model, base URL, cấu trúc phản hồi, và khả năng hiển thị trên sổ cái. Hãy để các prompt dài theo ngữ cảnh, lời gọi công cụ, tạo ảnh, và các job theo lô cho đến khi đường đi cơ bản hoạt động.

Bước 6: Để Claude Code gọi bất kỳ model được hỗ trợ nào từ một tác vụ

Sau khi bài kiểm tra nhỏ thành công, bạn có thể yêu cầu Claude Code định tuyến công việc tới một model phù hợp với tác vụ.

Ví dụ:

Use the flatkey skill. I need a second-model review of this function. Fetch the live catalog, select a coding-capable model returned by the catalog, run a small review request through Flatkey, and report the model ID, request result, and any request ID or usage fields returned. Do not print secrets.

Hoặc:

Use the flatkey skill. Compare two Flatkey-supported text models on this prompt. Keep both calls under 200 output tokens. Show the outputs side by side and tell me which one I should use for this low-risk internal summarization task.

Đó là mẫu "bất kỳ model nào" hoạt động tốt với Claude Code: Claude Code điều phối tác vụ, đọc tệp, áp dụng ngữ cảnh repo, và dùng Flatkey như một tuyến model bên ngoài được kiểm soát khi cần model thứ hai hoặc một họ model khác.

Đối với việc chọn model trong môi trường production, hãy kết hợp điều này với hướng dẫn danh mục model AI để Claude Code xem xét loại endpoint, đơn vị giá, tình trạng khả dụng, và trạng thái xác minh trước khi nó đề xuất một tuyến.

Bước 7: Chỉ dùng công cụ Flatkey sau khi kiểm tra

SKILL.md của Flatkey cũng bao gồm các công cụ tính phí theo mức sử dụng. Quy tắc quan trọng là Claude Code phải kiểm tra một công cụ trước khi chạy nó. Nó không được tự bịa ID công cụ, trường bắt buộc, giá, tên nhà cung cấp, hay đơn vị tính cước.

Một prompt mở đầu tốt là:

Use the flatkey skill. Open the Flatkey tools marketplace in the browser, inspect the search-related tools available to my account, and summarize the required fields and billing unit for one candidate tool. Do not execute the tool yet.

Sau đó, khi bạn sẵn sàng:

Use the flatkey skill. Run the inspected tool with a small limit and an idempotency key. Before execution, repeat the exact tool, required fields, expected billing unit, and maximum budget for my approval.

Cách này giúp Claude Code hữu ích mà không để một agent trôi vào các lệnh gọi trả phí không được kiểm soát.

Bước 8: Điều hướng lưu lượng Claude của Claude Code qua Flatkey khi cần

Thiết lập SKILL.md không giống với việc điều hướng chính Claude Code qua một gateway. Nếu mục tiêu của bạn là chạy các yêu cầu dòng Claude của Claude Code qua Flatkey, hãy cấu hình Claude Code như một client gateway theo định dạng Anthropic:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Không dùng hậu tố /v1 cho đường dẫn này. Claude Code và Anthropic SDK sẽ tự thêm route cần thiết. Sau khi đặt các biến, hãy khởi động Claude Code từ cùng shell đó và chạy:

/status

Tìm base URL của Anthropic và nguồn thông tin xác thực. Sau đó gửi một prompt ngắn và kiểm tra Flatkey Usage Logs. Nếu base URL không xuất hiện, nghĩa là Claude Code chưa nhận được biến môi trường.

Dùng cách này khi bạn muốn việc sử dụng Claude của Claude Code được ghi vào balance và sổ cái của Flatkey. Dùng đường dẫn skill khi bạn muốn Claude Code gọi các model và công cụ được Flatkey hỗ trợ từ repo của bạn.

Đối với các quyết định định tuyến liên quan, xem định tuyến API Claude so với GPT. Nếu trường hợp sử dụng của bạn là một agent gọi các công cụ bên ngoài, checklist Gemini API cho AI agents cũng hữu ích ngay cả khi họ model thay đổi, vì các kiểm soát là tương tự: ID model chính xác, retry có giới hạn, xác thực công cụ, và rà soát mức sử dụng.

Các lỗi thường gặp

Lỗi 1: Cho rằng SKILL.md thay đổi bộ não của Claude Code

Nó không làm vậy. Một skill cung cấp cho Claude Code các hướng dẫn và quy trình có thể tái sử dụng. Nó không biến vòng lặp agent của chính Claude Code thành GPT, Gemini, DeepSeek, Qwen hay một model khác.

Sai lầm 2: Dùng /v1 với ANTHROPIC_BASE_URL

Base URL tương thích OpenAI của Flatkey là:

https://router.flatkey.ai/v1

Định tuyến qua gateway của Claude Code dùng:

https://router.flatkey.ai

Giữ hai thứ này tách biệt.

Sai lầm 3: Commit thông tin xác thực trong cài đặt Claude

Project .claude/settings.json thường được chia sẻ cùng repo. Đừng đặt key ở đó. Hãy dùng biến môi trường shell, vault, hoặc .claude/settings.local.json chỉ khi repo của bạn bỏ qua file này và team của bạn chấp nhận quy trình local đó.

Sai lầm 4: Để agent tự đoán model ID

Luôn lấy /v1/models trước. Nếu một model ID không có trong phản hồi catalog trực tiếp cho key của bạn, đừng dùng nó.

Sai lầm 5: Chạy các công cụ trả phí trước khi kiểm tra chúng

Với Flatkey Tools, hãy kiểm tra trước các trường bắt buộc, ví dụ, đơn vị tính phí và giá chính xác. Sau đó dùng idempotency key và yêu cầu phê duyệt trước khi thực thi.

Danh sách kiểm tra thiết lập có thể sao chép

Dùng danh sách này cho một máy của nhà phát triển:

# 1. Cài skill Flatkey cho Claude Code
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

# 2. Xem lại nó
sed -n '1,200p' ~/.claude/skills/flatkey/SKILL.md

# 3. Xuất key Flatkey của bạn
export FLATKEY_API_KEY="sk-fk-your-key"

# 4. Khởi động Claude Code
claude

Sau đó nhập prompt:

Use the flatkey skill. Confirm the Flatkey skill is loaded, verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog, and run one tiny chat-completions smoke test through https://router.flatkey.ai/v1 using a model ID returned by the catalog.

Sau khi gọi xong, mở Flatkey Usage Logs và xác nhận request xuất hiện với model, trạng thái, số token, độ trễ và chi phí như mong đợi.

FAQ

Claude Code có thể dùng bất kỳ model nào thông qua SKILL.md không?

Bản thân Claude Code vẫn chạy trên Claude. Thiết lập SKILL.md cho phép Claude Code khám phá và gọi các model và công cụ được Flatkey hỗ trợ từ dự án của bạn, nên một tác vụ có thể dùng các model khác thông qua API của Flatkey khi phù hợp.

Điều này có giống với việc thay đổi ANTHROPIC_BASE_URL không?

Không. ANTHROPIC_BASE_URL=https://router.flatkey.ai định tuyến lưu lượng thuộc họ Claude của Claude Code qua một gateway. Cài https://flatkey.ai/SKILL.md dạy Claude Code cách vận hành các API và công cụ của Flatkey trong quá trình thực hiện tác vụ.

Tôi nên cài skill Flatkey ở phạm vi toàn cục hay trong repo?

Sử dụng ~/.claude/skills/flatkey/ cho mục đích cá nhân trên nhiều dự án. Sử dụng .claude/skills/flatkey/ khi repo nên mang theo một quy trình làm việc chung của nhóm. Chỉ commit tệp skill đã được rà soát, tuyệt đối không commit thông tin xác thực.

Tại sao hướng dẫn lại lấy /v1/models trước?

Vì khả năng sẵn có của model thay đổi. Danh mục Flatkey trực tiếp an toàn hơn so với tên model được chép từ trí nhớ, câu trả lời trong chat, hoặc một tài liệu cũ.

Tôi nên xác minh gì sau khi thiết lập?

Xác minh ba điều: Claude Code nhìn thấy skill, yêu cầu đến danh mục Flatkey thành công, và Usage Logs hiển thị yêu cầu kiểm tra với model, trạng thái, token, độ trễ và chi phí.

Tài liệu tham khảo chính thức

• Flatkey SKILL.md: https://flatkey.ai/SKILL.md
• Flatkey quickstart: https://docs.flatkey.ai/quickstart.md
• Hướng dẫn Flatkey Claude Code: https://docs.flatkey.ai/guides/claude-code.md
• Hướng dẫn Flatkey OpenAI SDK: https://docs.flatkey.ai/guides/openai-sdk.md
• Anthropic Claude Code skills: https://code.claude.com/docs/en/skills
• Tài liệu Anthropic Claude Code gateway: https://docs.anthropic.com/en/docs/claude-code/llm-gateway.md
• Hướng dẫn kết nối Anthropic gateway: https://docs.anthropic.com/en/docs/claude-code/llm-gateway-connect.md
• Tổng quan Anthropic Agent Skills: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview