🔑 Cấu Hình Khóa AI (API Keys)
AMBA kết hợp dữ liệu tài liệu cục bộ và năng lực tính toán trên máy tính của bạn với trí tuệ suy luận logic của các mô hình AI hàng đầu thế giới. Để vận hành AMBA, bạn chỉ cần trang bị khóa API từ ít nhất một nhà cung cấp AI được hỗ trợ.
🔒 Key Được Lưu Ở Đâu: Chỉ Trong Keychain Của Hệ Điều Hành
IMPORTANT
AMBA chỉ lưu API key trong keychain của hệ điều hành:
- macOS: macOS Keychain.
- Windows: Windows Credential Manager.
- Linux: Secret Service qua D-Bus (GNOME Keyring, KWallet 5.97 trở lên, hoặc KeePassXC đã bật Secret Service).
Không có cơ chế lưu dự phòng dạng văn bản thô hay trong cơ sở dữ liệu. Key không được ghi vào nhật ký và chỉ được gửi đến đúng nhà cung cấp sở hữu key. Sau khi lưu, AMBA đọc lại key và chỉ báo thành công khi keychain thực sự giữ key. Key được dán vào sẽ được cắt khoảng trắng thừa; key chứa ký tự xuống dòng, ký tự ẩn hoặc ký tự ngoài ASCII bị từ chối.
Linux không có keyring đang chạy: việc lưu thất bại với thông báo "Không có keychain hệ thống…", và Cài đặt → Chẩn đoán Hệ thống hiển thị keychain không khả dụng. Hãy cài đặt hoặc bật GNOME Keyring hay KWallet rồi khởi động lại AMBA (chi tiết).
TIP
macOS hỏi "AMBA wants to use your confidential information stored in … in your keychain"? AMBA giữ mọi key trong một mục keychain duy nhất và chỉ đọc mục đó nhiều nhất một lần trong mỗi lần chạy. Hãy chọn Always Allow (Luôn cho phép) để macOS không hỏi lại; các bản cập nhật có chữ ký giữ nguyên lựa chọn này. Bản build phát triển do bạn tự biên dịch sẽ hỏi lại sau mỗi lần build, vì mỗi bản build có chữ ký mới. Key lưu từ bản 0.5.11 trở về trước được chuyển vào mục duy nhất này ở lần đầu được dùng, nên bạn có thể được hỏi một lần cho mỗi key cũ, chỉ một lần.
Mục nào, và vì sao "Allow" chưa đủ. Hộp thoại ghi tên mục AMBA – saved API keys and connections (tài khoản amba-vault-v1) — mục duy nhất chứa mọi key và kết nối của AMBA. Mục do phiên bản cũ tạo vẫn hiện tên amba cho đến lần tiếp theo bạn lưu key hoặc đăng nhập. Allow (Cho phép) chỉ cấp quyền một lần, nên macOS sẽ hỏi lại ở lần mở AMBA sau và khi bạn lưu key hoặc đăng nhập Google; Always Allow (Luôn cho phép) cấp quyền lâu dài. Trong lúc chạy, AMBA không đụng lại keychain trừ khi một key thực sự thay đổi: việc làm mới phiên đăng nhập Google Drive mỗi giờ chỉ giữ trong bộ nhớ, không còn ghi lại vào keychain.
WARNING
Cập nhật từ 0.5.9? Các key đã lưu sau khi cập nhật lên 0.5.9 không được giữ lại. Hãy nhập lại trong Cài đặt → Mô hình AI. Key lưu từ bản 0.5.8 trở về trước tự động chuyển vào keychain ở lần khởi động đầu tiên.
📋 Các Nhà Cung Cấp Được Hỗ Trợ & Cách Lấy Khóa
1. Anthropic Claude (Rất Khuyến Nghị)
Tối ưu cho: Tổng hợp điều hành, phân rã dự án đa phòng ban và lập luận logic chuyên sâu.
- Truy cập Bảng điều khiển Anthropic.
- Đăng nhập hoặc tạo tài khoản doanh nghiệp.
- Chọn mục API Keys và bấm Create Key.
- Đặt tên khóa là
AMBA Desktopvà sao chép chuỗi ký tự vừa tạo (bắt đầu bằngsk-ant-...).
2. OpenAI
Tối ưu cho: Tác vụ điều hành thông thường, soạn thảo tài liệu chuẩn mực và phân tích nhanh.
- Truy cập Nền tảng OpenAI.
- Chọn Settings > API Keys.
- Bấm Create new secret key, đặt tên
AMBA Desktop, và sao chép khóa (bắt đầu bằngsk-proj-...).
3. Google Gemini
Tối ưu cho: Tiếp nhận khối lượng tài liệu khổng lồ và xử lý đa phương thức tốc độ cao.
- Truy cập Google AI Studio.
- Bấm nút Get API key và tạo khóa mới.
4. OpenRouter
Tối ưu cho: Kết nối tập trung đến hàng trăm mô hình mã nguồn mở và thương mại qua một tài khoản duy nhất.
- Truy cập OpenRouter.
- Vào mục Keys và tạo khóa API mới (bắt đầu bằng
sk-or-...).
5. TypeSafe AI (Động cơ Quyết định Jev System 1)
Tối ưu cho: Phân loại ý định dưới 1 giây và tự động định tuyến chế độ tư duy (Research, Plan, Agent).
- Truy cập TypeSafe AI.
- Lấy khóa API cho động cơ phân loại quyết định Jev.
⚙️ Hướng Dẫn Nhập Khóa Vào AMBA
- Khởi động phần mềm AMBA trên máy tính của bạn.
- Trên thanh điều hướng bên trái, bấm vào biểu tượng ⚙️ Cài đặt > Cài đặt Models (Model Settings).
- Hoàn tất thiết lập qua 3 bước trực quan:
- Bước 1: Mô hình Chính (Primary Model): Chọn mô hình suy luận chiến lược chính (ví dụ: Claude 3.5 Sonnet hoặc GPT-4o) và nhập khóa API.
- Bước 2: Chiến lược Dự phòng (Fallback): Cấu hình mô hình thay thế dự phòng khi bị nghẽn mạng hoặc vượt hạn mức (rate limit).
- Bước 3: Định tuyến Nâng cao & Thực nghiệm (Advanced & Experimental Routing): Nhập khóa OpenRouter hoặc TypeSafe AI (Jev) để bật tính năng tự động phân luồng chế độ tư duy siêu tốc.
- Bấm Save Key. Ô nhập sau đó hiển thị key đã được lưu trong keychain. Nếu keychain không giữ được key, một thông báo lỗi giải thích lý do và key không được lưu.