Hướng dẫn cấu hình Claude Code với Beeknoee

Claude Code là gì?

Claude Code là AI coding assistant của Anthropic — chạy trực tiếp trong terminal, hỗ trợ viết code, debug, quản lý file và chạy lệnh. Beeknoee Platform hỗ trợ Claude Code thông qua endpoint Anthropic Messages API tương thích.

💡 Khi dùng Claude Code qua Beeknoee, bạn có thể gọi tất cả hơn 130 models (không chỉ Claude) — hệ thống tự route phù hợp.

Yêu cầu

• Node.js 18+ (nodejs.org)
• API Key từ Beeknoee Platform

📌 Bước 1: Cài đặt Claude Code

npm install -g @anthropic-ai/claude-code

Kiểm tra cài đặt thành công:

claude --version

📌 Bước 2: Tạo API Key

1. Truy cập https://platform.beeknoee.com/api-keys
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Tạo API Key"
4. Copy API Key (dạng sk-bee-xxxx...)

⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!

🚀 Bước 3: Cấu hình qua Quick Setup (khuyên dùng)

3:58

Cách nhanh nhất — hệ thống tự sinh lệnh cài đặt cho bạn:

1. Vào trang API Keys

2. Chọn API Key bạn muốn dùng → nhấn ⚙️ Cấu hình API Key

3. Trong dialog, chuyển sang tab "Quick Setup"

4. Chọn tab Claude Code (mặc định đã chọn)

5. Chọn hệ điều hành — Windows hoặc macOS / Linux

6. Chọn Model Mapping (tuỳ chọn):

   • Haiku (Fast): Model nhanh, nhẹ — dùng cho task đơn giản
   • Sonnet (Default): Model mặc định khi gõ claude — cân bằng tốc độ/chất lượng
   • Opus (Powerful): Model mạnh nhất — dùng cho task phức tạp

   💡 Nếu không biết chọn gì, giữ mặc định là ổn!

7. Copy lệnh — nhấn nút Copy bên cạnh khung lệnh

8. Mở PowerShell (Windows) hoặc Terminal (macOS/Linux)

9. Dán lệnh và nhấn Enter

10. Sau khi cài xong, gõ claude để bắt đầu

Script tự động thực hiện:

• ✅ Set ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY trong settings.json (không ghi biến môi trường toàn máy)
• ✅ Smart merge settings.json — giữ nguyên permissions, hooks, mcpServers, model và statusline riêng của bạn
• ✅ Bật streaming toàn phần (xem mục dưới) — hết lỗi timeout khi model suy nghĩ lâu
• ✅ Cài đặt statusline (hiển thị số dư, model, chi phí) — chỉ khi bạn chưa có statusline riêng
• ✅ Bỏ qua màn hình giới thiệu lần đầu của CLI
• ✅ Sao lưu bản gốc vào ~/.claude/.beeknoee-backups/original/ (chụp 1 lần, không bao giờ bị đè)

💡 Ngoài lệnh cài đặt, khối Công cụ khác còn có 5 lệnh nữa: Xem trước, Kiểm tra máy, Kiểm chứng cấu hình, Gỡ riêng cấu hình Beeknoee, Gỡ cài đặt (khôi phục toàn bộ) — xem Quick Setup.

Muốn tự cấu hình bằng tay qua ~/.claude/settings.json thay vì Quick Setup? Video dưới đây làm từng bước:

3:32

⚡ Streaming — vì sao Quick Setup ghi thêm 4 biến

Claude Code luôn gửi request dạng streaming, không có công tắc nào để bật. Vấn đề nằm ở chỗ khác: khi một stream bị đứt giữa chừng, Claude Code tự thử lại bằng request không-stream. Request không-stream mà model suy nghĩ lâu sẽ bị proxy cắt và bạn nhận được lỗi timeout (Error 524) thay vì câu trả lời.

Vì vậy Quick Setup ghi thêm vào khối env:

⚠️ Đã chạy Quick Setup từ trước 08/08/2026? Hãy chạy lại lệnh để nhận khối này — cấu hình cũ không tự cập nhật. Kiểm tra nhanh bằng lệnh Kiểm tra máy (doctor): dòng Streaming phải là true.

📌 Bước 4: Kiểm tra kết nối

cd /path/to/your/project
claude

Trust workspace → Chọn Yes

Quick safety check: Is this a project you created or one you trust?

> 1. Yes, I trust this folder
  2. No, exit

👉 Chọn 1. Yes, I trust this folder → Enter

Xem trạng thái

Trong Claude Code, gõ /status để xem:

• Anthropic base URL → phải là https://platform.beeknoee.com/api
• Auth → phải hiện API key

Statusline

Sau khi cài đặt, Claude Code sẽ hiện statusline ở cuối terminal:

0% | Sonnet | 42,150đ | Cost: 53k tokens 72đ

• 0% — % context window đã dùng
• Sonnet — model đang dùng
• 42,150đ — số dư Beeknoee (cập nhật mỗi 30 giây)
• Cost: 53k tokens 72đ — chi phí session hiện tại

📌 Chọn model (tuỳ chọn)

Mặc định Claude Code dùng dòng Claude Sonnet (model ID dạng claude-sonnet-...). Bạn có thể đổi model bằng lệnh /model trong Claude Code.

Models khuyên dùng với Claude Code:

💡 Model ID và giá thay đổi theo phiên bản — xem ID chính xác (providerModelId) và giá realtime tại trang Models trên Dashboard, rồi truyền vào lệnh /model.

💡 Nếu bạn đã kết nối email qua BeeSynapse Integrations (Antigravity), các model Claude (Opus/Sonnet) có thể dùng miễn phí qua free quota!

🆓 Models miễn phí qua BeeSynapse

Khi đã kết nối email tại trang BeeSynapse Integrations, hệ thống tự động ưu tiên free quota:

Danh sách model free thay đổi theo quota nhà cung cấp — xem chính xác tại trang BeeSynapse Integrations. Bạn không cần thay đổi gì — Beeknoee tự route qua free quota trước, hết quota mới trừ VND.

🗑️ Gỡ cài đặt

Nếu muốn gỡ cấu hình Beeknoee và quay lại dùng Anthropic trực tiếp:

1. Vào trang API Keys → ⚙️ Cấu hình API Key → Quick Setup
2. Trong khối Công cụ khác, bấm Copy ở dòng "Gỡ cài đặt (khôi phục toàn bộ)" — hoặc dòng "Gỡ riêng cấu hình Beeknoee" nếu chỉ muốn bỏ Beeknoee mà giữ nguyên phần còn lại
3. Dán vào terminal và chạy

Script khôi phục từ bản chụp gốc ở ~/.claude/.beeknoee-backups/original/ — đúng trạng thái trước khi cài Beeknoee.

💡 Chỉ muốn bỏ phần Beeknoee mà giữ nguyên cấu hình bạn thêm sau đó? Dùng nút Gỡ riêng cấu hình Beeknoee — xem Quick Setup.

Xử lý lỗi thường gặp

"Unexpected value(s) for the anthropic-beta header"

Proxy có thể không hỗ trợ beta headers. Thêm vào biến môi trường:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

"Content block is not a text block"

Lỗi này xảy ra khi server tạm thời quá tải. Thử lại sau 1-2 phút.

Claude Code vẫn hiện màn hình login

• Kiểm tra file ~/.claude.json đã có "hasCompletedOnboarding": true
• Kiểm tra file JSON đúng cú pháp (validate tại jsonlint.com)
• Phải mở terminal MỚI sau khi sửa file

"Could not connect to Anthropic API"

• Kiểm tra ANTHROPIC_BASE_URL đã set đúng: https://platform.beeknoee.com/api
• Lưu ý URL không kết thúc bằng /v1 (Claude Code tự thêm)
• Kiểm tra kết nối internet

"Invalid API key" hoặc "authentication_error"

• Kiểm tra biến ANTHROPIC_API_KEY đã set đúng:

  # Linux/macOS
  echo $ANTHROPIC_API_KEY
  
  # Windows PowerShell
  echo $env:ANTHROPIC_API_KEY
  

• Kiểm tra key chưa bị thu hồi tại API Keys
• Đảm bảo key bắt đầu bằng sk-bee-

Timeout khi task dài

Tăng timeout:

export API_TIMEOUT_MS=600000  # 10 phút

"API Error 524" (timeout sau ~120s)

Claude Code mặc định đã streaming, nên về lý thuyết không bị Cloudflare cắt ở 120 giây. Nhưng thực tế nhiều người vẫn gặp 524 khi dùng qua Beeknoee. Lý do:

Khi một request streaming lỗi giữa chừng, Claude Code tự động thử lại ở chế độ non-streaming. Lần thử lại đó không còn stream nữa — nếu model "suy nghĩ" quá 120 giây, Cloudflare cắt kết nối và bạn nhận Error 524.

Vì Beeknoee là một gateway đứng sau Cloudflare, đây đúng là tình huống mà cơ chế lùi-về-non-streaming gây hại. Cách sửa: tắt hẳn nó đi.

Mở file settings.json của Claude Code (~/.claude/settings.json, hoặc .claude/settings.json trong dự án) và thêm:

{
  "env": {
    "CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK": "1",
    "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT": "1",
    "API_TIMEOUT_MS": "600000"
  }
}

💡 Nếu bạn dùng MCP: khi ANTHROPIC_BASE_URL trỏ về máy chủ không phải Anthropic (tức là khi dùng Beeknoee), Claude Code tự tắt MCP tool search. Muốn bật lại, thêm "ENABLE_TOOL_SEARCH": "true" vào khối env.

Cấu hình đầy đủ (tuỳ chọn)

Nếu bạn muốn ép Claude Code luôn dùng một model mạnh nhất định qua Beeknoee:

{
  "model": "<MODEL_ID>",
  "effortLevel": "xhigh",
  "alwaysThinkingEnabled": true,
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<MODEL_ID>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<MODEL_ID>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<MODEL_ID>",
    "CLAUDE_CODE_ALWAYS_ENABLE_EFFORT": "1",
    "CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK": "1",
    "API_TIMEOUT_MS": "600000"
  }
}

Thay <MODEL_ID> bằng Model ID thật, copy từ trang Các Mô Hình AI. Ba biến ANTHROPIC_DEFAULT_*_MODEL ánh xạ cả ba mức Haiku/Sonnet/Opus về cùng một model, nên gõ claude là luôn ra model bạn chọn.

⚠️ Về permissions.defaultMode: "bypassPermissions" — bạn có thể thấy thiết lập này trong một số cấu hình được chia sẻ trên mạng. Nó không liên quan gì đến lỗi 524. Tác dụng thật của nó là bỏ qua mọi lời hỏi xác nhận trước khi Claude Code chạy lệnh, sửa file hay xoá dữ liệu. Chỉ dùng khi bạn hiểu rõ rủi ro và đang làm trong môi trường cô lập (container, máy ảo). Không cần thiết để sửa 524.

Nếu bạn gọi Beeknoee bằng SDK/script khác (OpenAI SDK, curl…) mà gặp 524, hãy đặt "stream": true trong request. Xem Error Handling.

"Model not found"

• Kiểm tra Model ID tại trang Các Mô Hình AI
• Đảm bảo dùng đúng providerModelId (ví dụ dạng claude-sonnet-..., không phải tên hiển thị) — copy chính xác từ trang Models

Giải thích cơ chế

Claude Code → POST /v1/messages (format Anthropic)
                    ↓
              Beeknoee Backend (tự động dịch format)
                    ↓
              Xử lý như bình thường: resolve key → gọi provider → billing
                    ↓
              Trả response (format Anthropic) → Claude Code

Claude Code gửi request theo format Anthropic (/v1/messages), Beeknoee nhận và tự động chuyển đổi format nội bộ, xử lý qua hệ thống AI Proxy (cùng hệ thống với /v1/chat/completions), rồi trả kết quả lại theo đúng format Anthropic.

So sánh với dùng Anthropic trực tiếp

HOÀN TẤT! 🎉

Cần hỗ trợ thêm? Sử dụng Support Chat (góc dưới phải trên platform) hoặc liên hệ qua email.

Dùng Claude Code ở nơi khác

Cùng một API key, Claude Code còn chạy được ở 2 nơi nữa — mỗi nơi khai báo một kiểu khác nhau:

Xem thêm hướng dẫn tích hợp khác

• Quick Setup — cài 1 lệnh + 4 công cụ kiểm tra
• Codex CLI — OpenAI coding CLI
• OpenCode — AI coding CLI (OpenAI-compatible)
• Cursor — AI-first code editor
• Cline — VS Code AI agent
• Continue — VS Code/JetBrains extension
• Windsurf — AI IDE với Cascade Flow
• Zed — Code editor Rust siêu nhanh
• Kilo Code — VS Code AI coding agent
• Aider — AI pair programming CLI