Hướng dẫn cấu hình Claude Desktop với Beeknoee
Claude Desktop là gì?
Claude Desktop là ứng dụng desktop do chính Anthropic phát hành (macOS / Windows / Linux beta), có 3 tab: Chat, Cowork và Code. Tab Code chính là Claude Code nhưng có giao diện đồ hoạ — chạy nhiều phiên song song, xem diff trực quan, terminal và editor tích hợp.
Beeknoee nối được vào tab Code thông qua chế độ Third-Party Inference → Gateway, vì Beeknoee nói đúng chuẩn Anthropic Messages API mà chế độ này yêu cầu.
⚠️ Đọc kỹ trước khi làm: cấu hình này chỉ đổi nguồn suy luận của tab Code. Tab Chat và Cowork vẫn chạy bằng tài khoản claude.ai của bạn (gói Pro/Max) và không đi qua Beeknoee. Nếu bạn muốn dùng Beeknoee cho việc chat thông thường, hãy dùng Bee AI Studio trên Dashboard.
💡 Chỉ cần dùng dòng lệnh? Xem Claude Code — nhanh hơn và có Quick Setup tự động.
Yêu cầu
- Claude Desktop đã cài và đã đăng nhập ít nhất một lần
- API Key từ Beeknoee Platform
- Trên Windows: cần cài sẵn Git for Windows để tab Code hoạt động
📌 Bước 1: Tạo API Key
- Truy cập https://platform.beeknoee.com/api-keys
- Đăng nhập bằng tài khoản Google
- Nhấn "Tạo API Key"
- Copy API Key (dạng
sk-bee-xxxx...)
⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!
📌 Bước 2: Bật Developer Mode
Form cấu hình gateway nằm trong menu Developer, mà menu này mặc định bị ẩn:
- Mở Claude Desktop
- Vào Help → Troubleshooting → Enable Developer Mode
- App tự khởi động lại, trên thanh menu xuất hiện mục Developer
📌 Bước 3: Điền thông tin Beeknoee
- Vào Developer → Configure Third-Party Inference…
- Ở mục Connection, đặt Inference provider = Gateway
- Điền thẻ Gateway credentials:
| Field | Giá trị |
|---|---|
| Gateway base URL | https://platform.beeknoee.com |
| Gateway API key | sk-bee-YOUR_API_KEY |
| Credential kind | Static API key (mặc định) |
| Gateway auth scheme | Bearer (mặc định) |
- Lưu lại và khởi động lại app
💡 Base URL không có
/v1— Claude Desktop tự nối/v1/messagesphía sau, giống Claude Code CLI. Dạnghttps://platform.beeknoee.com/apicũng chạy đúng (đây là dạng Quick Setup ghi cho bản CLI).
💡 Beeknoee chấp nhận cả Bearer lẫn x-api-key, nên bạn để mặc định Bearer là được.
📌 Bước 4: Chọn model
Mở tab Code, tạo một phiên mới rồi chọn model ở khung chat.
Claude Desktop tự lấy danh sách model từ GET /v1/models của Beeknoee, nhưng chỉ hiển thị những model có ID nhận diện được là Claude. Nghĩa là:
| Model | Hiện trong picker? |
|---|---|
claude-sonnet-..., claude-opus-..., claude-haiku-... | ✅ Có |
gpt-..., gemini-..., grok-..., deepseek-... | ❌ Không |
⚠️ Giới hạn thật của Claude Desktop: muốn ép hiện model không phải Claude thì phải khai
inferenceModelsqua file cấu hình MDM (dành cho quản trị viên doanh nghiệp), không làm được từ giao diện. Nếu bạn cần chạy GPT/Gemini/Grok qua Beeknoee, hãy dùng Claude Code CLI (đổi model bằng/model) hoặc các extension VS Code.
📌 Bước 5: Kiểm tra
Gõ một câu bất kỳ trong tab Code. Nếu có phản hồi bình thường là xong.
Sau đó mở trang Usage trên Dashboard — request vừa rồi phải xuất hiện trong lịch sử. Đây là cách chắc chắn nhất để biết bạn đang chạy qua Beeknoee chứ không phải tài khoản claude.ai.
⚠️ Những thứ bị tắt khi bật gateway
Đây là hành vi của Claude Desktop, không phải giới hạn của Beeknoee:
- Chỉ chạy phiên local — không còn tuỳ chọn SSH hay môi trường cloud của Anthropic
- Remote Control (điều khiển từ điện thoại) không dùng được
- Voice dictation không dùng được
Muốn lấy lại các tính năng đó thì gỡ cấu hình gateway và quay về đăng nhập claude.ai.
🔧 Lỗi thường gặp
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
Gateway was unreachable | App không gọi được base URL lúc khởi động | Kiểm tra lại URL (không thừa /v1/messages), kiểm tra mạng/proxy công ty |
| Model picker trống | Không có model nào ID dạng claude-* khả dụng với key | Kiểm tra key còn hiệu lực; nếu key bị giới hạn model (tab Cài đặt) thì phải cho phép ít nhất 1 model Claude |
| Form bị khoá, không sửa được | Máy đang nhận cấu hình do quản trị viên phân phối | Cấu hình từ MDM có ưu tiên cao hơn — liên hệ quản trị viên |
| Trả lời được nhưng Usage không ghi nhận | Tab đang dùng là Chat, không phải Code | Chuyển sang tab Code — chỉ tab này đi qua gateway |
401 / báo key sai | Key sai, hết hạn hoặc đã revoke | Tạo key mới tại API Keys |
Xem thêm Xử lý lỗi.
🗑️ Gỡ cấu hình
Vào Developer → Configure Third-Party Inference… → đổi Inference provider về mặc định (không phải Gateway) → khởi động lại app. Tài khoản claude.ai của bạn vẫn còn nguyên, không cần đăng nhập lại.
Xem thêm
- Claude Code — bản CLI, có Quick Setup tự động và dùng được mọi model
- VS Code — extension Claude Code và các extension OpenAI-compatible
- Quick Setup — cài đặt 1 lệnh cho 4 agent