Gemini CLI với endpoint tùy chỉnh và mô hình miễn phí
Gemini CLI là tác nhân lập trình mã nguồn mở của Google, chạy trong terminal. Nó có thể gửi yêu cầu tới một URL gốc tùy chỉnh. Hướng dẫn này trỏ Gemini CLI tới FreeLLMAPI, nơi phục vụ API Gemini gốc tại /v1beta. Các yêu cầu của bạn sau đó đi tới nhóm nhà cung cấp miễn phí của bạn, có thể bao gồm khóa API Gemini miễn phí.
Mã, tên mô hình và nhãn danh mục trực tiếp được hiển thị bằng tiếng Anh.
Thay đổi năm 2026 với gói miễn phí của Gemini CLI
Đọc phần này trước. Google đã thay đổi việc dùng miễn phí Gemini CLI trong năm 2026. Trang hạn mức Gemini CLI viết: "Người dùng gói chưa trả phí và Google One: Gemini CLI đã được thay bằng Antigravity CLI vào ngày 18 tháng 6 năm 2026."
Thông báo của Google nói rằng Gemini CLI vẫn khả dụng qua khóa API Gemini trả phí và cho khách hàng doanh nghiệp.
- Đăng nhập Google ở gói miễn phí: không còn được Gemini CLI phục vụ cho tài khoản người tiêu dùng.
- Khóa API Gemini với URL gốc tùy chỉnh: tài liệu cấu hình Gemini CLI vẫn ghi
GOOGLE_GEMINI_BASE_URL. Với biến này, Gemini CLI gửi yêu cầu tới URL bạn đặt, không tới Google. - Khóa API Gemini miễn phí: Google AI Studio vẫn liệt kê gói miễn phí cho API Gemini. FreeLLMAPI có thể dùng các khóa đó, cùng với khóa từ nhà cung cấp khác.
Hướng dẫn này dùng phương pháp thứ hai. FreeLLMAPI trả lời các yêu cầu và gửi mỗi yêu cầu tới một mô hình miễn phí trong nhóm của bạn.
Bước 1: Cài đặt FreeLLMAPI và Gemini CLI
Cài đặt cả hai
curl -fsSL https://freellmapi.co/install.sh | bash
npm install -g @google/gemini-cliMở http://localhost:3001. Thêm ít nhất hai khóa nhà cung cấp miễn phí trên trang Keys. Khóa Google AI Studio miễn phí là khóa đầu tiên tốt. Sao chép khóa thống nhất của bạn từ cùng trang đó.
Bước 2: Trỏ Gemini CLI tới cổng
Đặt hai biến môi trường rồi khởi động Gemini CLI. URL gốc là nguồn máy chủ, không có /v1beta. Gemini CLI tự thêm đường dẫn API.
macOS hoặc Linux
export GOOGLE_GEMINI_BASE_URL=http://localhost:3001
export GEMINI_API_KEY=<unified-key>
geminiWindows PowerShell
$env:GOOGLE_GEMINI_BASE_URL="http://localhost:3001"
$env:GEMINI_API_KEY="<unified-key>"
geminiKhi Gemini CLI hỏi phương thức xác thực, chọn Use Gemini API key. Để lưu lựa chọn, đặt trong ~/.gemini/settings.json:
~/.gemini/settings.json
{
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
}
}GEMINI_API_KEY. Một issue của Gemini CLI báo rằng phiên bản 0.44.x lỗi với "Invalid auth method selected" khi dùng GOOGLE_API_KEY cùng GOOGLE_GEMINI_BASE_URL. Nếu GOOGLE_API_KEY đã được đặt, xóa nó bằng unset GOOGLE_API_KEY.Bước 3: Ánh xạ tên mô hình Gemini sang mô hình miễn phí
Gemini CLI yêu cầu tên mô hình Gemini, ví dụ gemini-2.5-flash. FreeLLMAPI không gửi các tên này trực tiếp tới Google. Nó phân giải chúng qua bản đồ họ Gemini trên tab Keys, Agents. Ánh xạ mỗi họ (Pro, Flash và Flash-Lite) sang Auto hoặc sang một mô hình danh mục đã ghim.
- Với Auto, bộ định tuyến chọn một mô hình miễn phí cho mỗi yêu cầu. Khi một nhà cung cấp gửi lỗi 429, nó thử nhà cung cấp tiếp theo.
- Catalog id cũng dùng được làm tên mô hình. Khởi động Gemini CLI bằng
gemini -m <catalog-id>, hoặc đặtGEMINI_MODEL. - Gemini CLI là tác nhân có công cụ. Ánh xạ các họ tới mô hình có gọi công cụ và cửa sổ ngữ cảnh lớn.
Bảng đầu tiên liệt kê các mô hình Gemini miễn phí trong danh mục hiện nay. Bảng thứ hai liệt kê các mô hình miễn phí khác mà bạn có thể ánh xạ tới một họ Gemini.
| Mô hình | Miễn phí trên | Ngữ cảnh | Giới hạn miễn phí (ưu đãi tốt nhất) | Công cụ | Thị giác |
|---|---|---|---|---|---|
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Có | Có |
| Gemini Flash (latest alias) | Google AI Studio | - | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Gemini 3.5 Flash | Google AI Studio | 1M | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Gemini 3.8 Live | Google AI Studio | - | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Gemini 3.8 Live Extended Thinking | Google AI Studio | - | 10 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
| Gemini 3.5 Flash Lite | Google AI Studio | 1M | 15 yêu cầu/phút 20 yêu cầu/ngày 250,000 token/phút ~3M | Có | Có |
Đang hiển thị 8 trong số 14 mô hình miễn phí phù hợp. Xem tất cả mô hình.
Dữ liệu trực tiếp từ danh mục FreeLLMAPI (phiên bản 2026.11.19, đã kiểm tra 2026-11-19). Giới hạn miễn phí thay đổi thường xuyên. Danh mục được kiểm tra mỗi ngày.
| Mô hình | Miễn phí trên | Ngữ cảnh | Giới hạn miễn phí (ưu đãi tốt nhất) | Công cụ | Thị giác |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 yêu cầu/phút 1 req/min per model | Có | Không |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 yêu cầu/phút 40 RPM | Có | Có |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Có | Không |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Có | Có |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Có | Có |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 yêu cầu/phút 50 yêu cầu/ngày 50 req/day account-wide (1,000 after a $10 purchase) | Có | Có |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 yêu cầu/phút 50 yêu cầu/ngày Shared rate limit | Có | Không |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 yêu cầu/phút 250 yêu cầu/ngày 70,000 token/phút ~6M | Có | Có |
Đang hiển thị 8 trong số 104 mô hình miễn phí phù hợp. Xem tất cả mô hình.
Dữ liệu trực tiếp từ danh mục FreeLLMAPI (phiên bản 2026.11.19, đã kiểm tra 2026-11-19). Giới hạn miễn phí thay đổi thường xuyên. Danh mục được kiểm tra mỗi ngày.
Giới hạn gói miễn phí của Gemini
Trang giới hạn tốc độ của Google nói rằng giới hạn áp dụng theo dự án, không theo khóa API. Thêm khóa trong cùng một dự án không làm tăng hạn mức. Google cũng nói rằng giới hạn không được đảm bảo và bạn có thể xem giới hạn hiện tại trong Google AI Studio. Mô hình preview có giới hạn thấp hơn.
Một khóa Gemini Flash miễn phí cho phép ít yêu cầu mỗi ngày. Một tác vụ Gemini CLI có thể gửi nhiều yêu cầu. Thêm khóa từ nhà cung cấp khác, để bộ định tuyến tiếp tục khi hạn mức Gemini dừng. Bề mặt gốc hỗ trợ generateContent, streamGenerateContent với ?alt=sse, countTokens và danh sách mô hình.
FreeLLMAPI nhận khóa trong tiêu đề x-goog-api-key, dưới dạng Bearer token, hoặc trong tham số truy vấn ?key= của Gemini. Ưu tiên tiêu đề, vì khóa trong URL có thể lọt vào lịch sử shell và nhật ký proxy.
Xử lý sự cố
| Vấn đề | Nguyên nhân | Cách khắc phục |
|---|---|---|
| Gemini CLI mở đăng nhập Google | Loại xác thực chưa được đặt thành khóa API Gemini | Chọn Use Gemini API key, hoặc đặt security.auth.selectedType |
| "Invalid auth method selected" | GOOGLE_API_KEY được dùng với URL gốc tùy chỉnh | Dùng GEMINI_API_KEY và unset GOOGLE_API_KEY |
| Yêu cầu đi tới Google, không tới cổng | GOOGLE_GEMINI_BASE_URL chưa được đặt trong shell này | Export biến, rồi khởi động lại gemini |
404 khi gọi mô hình | URL gốc có /v1beta | Chỉ dùng nguồn http://localhost:3001 |
| Gọi công cụ lỗi | Họ Gemini được ánh xạ tới mô hình có gọi công cụ yếu | Ánh xạ họ tới một mô hình trong các bảng trên |
| "Tất cả mô hình bị giới hạn tốc độ sau N lần thử" | Mọi khóa đều ở mức giới hạn | Thêm khóa từ nhiều nhà cung cấp hơn, hoặc chờ thời gian nghỉ |
Câu hỏi thường gặp
Gemini CLI còn miễn phí không?
Google đã chấm dứt việc dùng Gemini CLI miễn phí với đăng nhập Google cho người dùng chưa trả phí và người dùng Google One vào ngày 18 tháng 6 năm 2026. CLI vẫn hỗ trợ URL gốc tùy chỉnh, nên nó có thể chạy trên cổng miễn phí như FreeLLMAPI.
Làm sao dùng Gemini CLI với endpoint tùy chỉnh?
Đặt GOOGLE_GEMINI_BASE_URL thành nguồn của endpoint và GEMINI_API_KEY thành khóa của nó, rồi chọn Use Gemini API key. Endpoint phải nói API Gemini gốc trên /v1beta.
Gemini CLI có dùng được mô hình không phải Gemini không?
Có, qua FreeLLMAPI. Cổng ánh xạ tên họ Gemini Pro, Flash và Flash-Lite sang Auto hoặc sang bất kỳ mô hình danh mục nào, ví dụ mô hình Qwen hoặc GLM.
Giới hạn gói miễn phí của API Gemini là gì?
Google đặt giới hạn theo dự án, không theo khóa, và hiển thị giá trị hiện tại trong Google AI Studio. Bảng trên trang này liệt kê các mô hình Gemini miễn phí hiện nay và giới hạn của chúng từ danh mục FreeLLMAPI.
Vì sao tôi nhận 'Invalid auth method selected'?
Một issue của Gemini CLI báo lỗi này ở phiên bản 0.44.x khi GOOGLE_API_KEY được dùng cùng GOOGLE_GEMINI_BASE_URL. Dùng GEMINI_API_KEY và unset GOOGLE_API_KEY.
Hướng dẫn liên quan
- free gemini api
- Gemini API vượt hạn mức (429 RESOURCE_EXHAUSTED)
- Cách dùng Claude Code miễn phí
- Dùng Codex CLI với mô hình miễn phí
- API model lập trình miễn phí tốt nhất
Nguồn
- Gemini CLI docs: configuration reference (đã kiểm tra 20 November 2026)
- Gemini CLI docs: authentication (đã kiểm tra 20 November 2026)
- Gemini CLI docs: quota and pricing (đã kiểm tra 20 November 2026)
- Google Developers Blog: transitioning Gemini CLI to Antigravity CLI (đã kiểm tra 20 November 2026)
- Gemini CLI issue 27550: auth with a custom base URL (đã kiểm tra 20 November 2026)
- Google AI Studio: rate limits (đã kiểm tra 20 November 2026)
- FreeLLMAPI docs: native Gemini API (đã kiểm tra 20 November 2026)