Gemini CLI

Gemini CLI là tác tử terminal mã nguồn mở của Google, có thể hiểu dự án, phân tích tệp và dùng lệnh cùng công cụ sau khi được cấp quyền. Cấu hình địa chỉ Gemini API, API Key và ID mô hình để Gemini CLI dùng điểm vào tương thích Gemini Generate Content của AGTCloud.

Hướng dẫn này chỉ trình bày kết nối cơ bản và quy trình kiểm tra an toàn của Gemini CLI. Sửa tệp, lệnh Shell, gọi hàm và khả năng tác tử khác phụ thuộc mô hình đích cùng mức hỗ trợ thực tế của các cấu trúc Gemini Parts, Function Call và giao thức liên quan.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

• Cài Node.js phiên bản 20 trở lên;
• Chuẩn bị terminal Bash, Zsh hoặc PowerShell;
• Tạo AGTCloud API Key trên trang API Keys;
• Sao chép ID mô hình mà Key hiện tại nhìn thấy và hỗ trợ Gemini Generate Content từ danh mục mô hình;
• Chuẩn bị thư mục thử nghiệm không chứa mã nhạy cảm hoặc thông tin xác thực của môi trường production.

MODEL_ID là giá trị giữ chỗ cần thay thế, không phải tên mô hình thực tế. Dùng ID mô hình mà API Key hiện tại nhìn thấy và hỗ trợ Gemini Generate Content.

Cài đặt Gemini CLI

Nên cài phiên bản ổn định hiện tại. Các cách cài đặt đều cung cấp cùng lệnh gemini.

npm install -g @google/gemini-cli

Sau khi cài đặt, kiểm tra phiên bản:

gemini --version

Nếu không tìm thấy lệnh, mở lại terminal và xác nhận thư mục lệnh npm toàn cục nằm trong PATH.

Cấu hình AGTCloud

Gemini CLI cần bốn biến môi trường: API Key, ID mô hình, địa chỉ Gemini API tùy chỉnh và phương thức xác thực Bearer.

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

Giải thích cấu hình

Hướng dẫn này không đặt GOOGLE_GENAI_API_VERSION, để Gemini CLI dùng phiên bản mặc định v1beta của Gemini API. Cũng không ghi đường dẫn yêu cầu generateContent đầy đủ vào Base URL.

Lưu cấu hình cấp người dùng

Sau khi xác nhận cấu hình tạm thời hoạt động, có thể ghi các biến vào tệp .env cấp người dùng của Gemini CLI. Tệp có thể chứa API Key thật, không đưa vào kho mã.

~/.gemini/.env

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI tìm tệp môi trường trong thư mục làm việc hiện tại và các thư mục cha. .env hoặc .gemini/.env gần hơn trong dự án có thể được ưu tiên hơn cấu hình cấp người dùng; khi cấu hình không có hiệu lực, kiểm tra các tệp này trước.

Cố định phương thức xác thực API Key

Gemini CLI hỗ trợ nhiều cách xác thực Google. Khi dùng qua AGTCloud, chọn Gemini API Key, không chọn đăng nhập Google hoặc Vertex AI.

Hợp nhất cấu hình dưới đây vào settings.json cấp người dùng; không ghi đè chủ đề, quyền hoặc thiết lập khác đã có:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Vị trí tệp cấu hình:

Sau khi lưu, thoát hoàn toàn rồi khởi chạy lại Gemini CLI. selectedType chọn quy trình xác thực API Key, còn GEMINI_API_KEY_AUTH_MECHANISM=bearer tạo Bearer Header theo yêu cầu AGTCloud; hai thiết lập không thay thế nhau.

Chọn mô hình

Mô hình mặc định do GEMINI_MODEL quyết định. Để chỉ định mô hình tạm thời cho một phiên, chạy:

gemini --model MODEL_ID

/model trong phiên tương tác có thể là điểm vào bổ trợ, nhưng danh sách không nhất thiết tự chứa mọi mô hình do API Key AGTCloud hiện tại trả về. Nếu mô hình không tồn tại hoặc không hiển thị, sao chép lại ID đầy đủ từ danh mục mô hình và ưu tiên chỉ định qua GEMINI_MODEL hoặc --model.

Kiểm tra kết nối

gemini -p "Chỉ trả lời: Kết nối AGTCloud thành công." --output-format json

gemini -p "@README.md Hãy tóm tắt mục đích dự án thành ba ý, không sửa bất kỳ tệp nào." --output-format json

gemini

Câu hỏi thường gặp

Nếu chưa xác định được vấn đề, ghi lại thời gian yêu cầu, API Base URL, ID mô hình, phiên bản Gemini CLI, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi API Key đầy đủ hoặc tệp .env chứa thông tin xác thực.

Khuyến nghị bảo mật

• Không ghi API Key thật vào kho mã, script dùng chung, ảnh chụp màn hình, nhật ký hoặc lịch sử trò chuyện;
• Nên kiểm tra bằng biến môi trường tạm thời trước, chỉ lưu cấu hình cấp người dùng sau khi thành công;
• Đặt quyền truy cập cục bộ phù hợp cho .env và tránh đồng bộ lên dịch vụ lưu trữ công khai;
• Giữ phê duyệt thủ công trong lần đầu dùng công cụ và kiểm tra trên dự án ngoài môi trường production;
• Trước khi chia sẻ thông tin khắc phục sự cố, xóa Key đầy đủ, tên người dùng, đường dẫn cục bộ và mã nguồn nghiệp vụ.

Bước tiếp theo

• API Key, Base URL và xác thực
• Gemini Generate Content API Reference
• Gemini Stream Generate Content API Reference
• Chọn giao thức
• Lỗi và khắc phục sự cố