Chuyển từ Gemini CLI sang Antigravity CLI: Hướng dẫn

Ngày 19 tháng 5 năm 2026, Google thông báo sẽ ngừng Gemini CLI cũ trên tất cả các gói Free, Pro và Ultra vào ngày 18 tháng 6. Hai tuần sau khi hướng dẫn này được đăng, lệnh gemini sẽ ngừng xử lý yêu cầu. Chuyển từ Gemini CLI sang Antigravity CLI bằng lệnh agy là cách duy nhất để tiếp tục sử dụng các công cụ của Google. agy được xây dựng bằng Go và khởi động nhanh hơn hàng chục lần.

Nếu bạn đang chạy bất kỳ thứ gì trên Gemini CLI — tập lệnh CI, tác vụ cron chạy hằng đêm, tiện ích Gemini Code Assist cho IDE — hướng dẫn này giải thích cách chuyển đổi trong một buổi tối mà không làm hỏng bất cứ thứ gì.

Chính xác thì điều gì sẽ ngừng hoạt động vào ngày 18 tháng 6 năm 2026?#

Đây không phải là “đóng cửa toàn bộ dự án”, mà là ngừng dịch vụ cho ba gói phổ biến nhất. Những ai bị ảnh hưởng:

Trích từ Google Developers Blog chính thức:

Nếu bạn dùng gói Free như phần lớn nhà phát triển cá nhân và đang nghĩ “nhưng tôi có tài khoản trả phí mà” — hãy kiểm tra chính xác cách thanh toán cho khóa API của bạn. AI Pro không phải thanh toán qua Cloud; đây là gói đăng ký Google AI cá nhân và sẽ bị vô hiệu hóa. Thanh toán qua Cloud bằng dự án trả phí sẽ không bị vô hiệu hóa.

Tại sao Google lại ngừng Gemini CLI?#

gemini cũ khởi động trong “hàng trăm mili giây” vì Node.js cần thời gian khởi động. agy mới được xây dựng thành một tệp nhị phân Go tĩnh duy nhất và khởi động trong “vài mili giây”. Với CI và các tập lệnh gọi CLI hàng trăm lần mỗi lần chạy, sự khác biệt này rất đáng kể.

Google nói gì về tốc độ và lý do:

Các tính năng chính của Gemini CLI đều đã được chuyển sang:

• Kỹ năng tác nhân (Agent Skills) — thư mục .gemini/skills/ hiện nằm trong .agents/skills/.
• Hooks — dùng cùng sự kiện (PreToolUse, PostToolUse, v.v.); cú pháp hầu như không thay đổi.
• Tác nhân phụ — hoạt động như trước và cấu hình của chúng được tự động chuyển đổi.
• Tiện ích mở rộng — được đổi tên thành plugin Antigravity và nhập bằng một lệnh.

Những thứ không được chuyển đổi suôn sẻ là máy chủ MCP và các tập lệnh cũ truy cập trực tiếp vào .gemini/config.json. Theo thảo luận trên GitHub, một số người dùng cho biết cấu hình MCP bị lỗi và phải viết lại thủ công. Phần bên dưới sẽ nói riêng về vấn đề này.

Google không đóng dự án mã nguồn mở Gemini CLI:

Điều đó có nghĩa là bạn có thể fork dự án và tiếp tục dùng với khóa Gemini API của riêng mình. Nhưng giờ đây đây là thiết lập trả phí qua thanh toán Cloud; phương thức Code Assist miễn phí đã kết thúc.

Cách cài đặt Antigravity CLI: lệnh cho macOS, Linux và Windows#

Trước khi bắt đầu, hãy tự kiểm tra nhanh: bạn đang dùng gói nào? Nếu có dự án Cloud trả phí và không bị hạn chót ngày 18 tháng 6, việc chuyển đổi hữu ích nhưng không khẩn cấp. Nếu bạn đang dùng Free/Pro/Ultra và có thứ gì đó chạy trên CLI, hãy chuyển ngay khi các gói vẫn còn hoạt động để có thể so sánh cách vận hành trên cùng một tác vụ.

macOS và Linux

Lệnh một dòng dùng curl:

curl -fsSL https://antigravity.google/cli/install.sh | bash

Tập lệnh phát hiện nền tảng, tải tệp nhị phân agy, kiểm tra checksum và đặt vào ~/.local/bin. Nếu thư mục này chưa có trong PATH, hãy thêm vào:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Kiểm tra xem có thể gọi tệp nhị phân hay không:

which agy
agy --version

Windows (PowerShell)

irm https://antigravity.google/cli/install.ps1 | iex

Tệp nhị phân sẽ được cài tại C:\Users\[your_name]\AppData\Local\agy\bin. Trình cài đặt sẽ tự động cập nhật PATH, nhưng hãy mở cửa sổ PowerShell mới để tải lại các biến.

Windows (CMD)

Nếu chính sách của công ty chặn PowerShell:

curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

Xác minh cài đặt

Sau khi cài đặt trên hệ điều hành bất kỳ, hãy chạy:

agy doctor

Lệnh này kiểm tra phiên bản tệp nhị phân, xem cấu hình có tồn tại không, xác thực và khả năng truy cập mạng tới antigravity.google. Nếu không thể kết nối với Google, vấn đề nằm ở khu vực của bạn hoặc proxy.

Xác thực

Lần đầu chạy agy mà không có đối số, chương trình sẽ mở trình hướng dẫn thiết lập:

1. Chọn giao diện chủ đề.
2. Chọn phương thức xác thực: Google OAuth (cho tài khoản cá nhân) hoặc khóa API.
3. Có thể nhập cấu hình từ .gemini/ ngay lúc này.

Nếu chọn OAuth, trình duyệt sẽ mở và chuyển hướng bạn đến accounts.google.com; bạn cần chấp thuận chia sẻ dữ liệu. Sau đó, CLI sẽ hoạt động.

Cách chuyển cấu hình và plugin từ .gemini sang .agents#

Từng bước:

1. agy plugin import gemini

   Chạy lệnh từ thư mục bất kỳ. Lệnh sẽ chuyển các plugin toàn cục từ ~/.gemini/ sang ~/.agents/. Để chuyển plugin của workspace (nằm cạnh dự án), hãy chạy lệnh trong thư mục dự án.

2. mv .gemini/skills/ .agents/skills/

   Di chuyển kỹ năng bằng cách đổi tên thư mục thủ công. Định dạng tệp bên trong vẫn như cũ; không cần viết lại Markdown.

3. agy inspect

   Hiển thị plugin, kỹ năng, hooks và tác nhân phụ nào đang hoạt động. So sánh với danh sách bạn đã có trong Gemini CLI — không nên có mục nào bị thiếu.

4. agy config --edit

   Mở cấu hình bằng trình chỉnh sửa mặc định ($EDITOR). Nếu có mục nào không được tự động nhận diện, hãy chỉnh sửa thủ công.

5. agy doctor

   Kiểm tra lần cuối: tệp nhị phân, xác thực, plugin và mạng. Nếu cả bốn mục đều màu xanh, quá trình chuyển cấu hình đã hoàn tất.

Tôi khuyên nên giữ thư mục .gemini/ cũ làm bản sao lưu trong một tháng, phòng trường hợp có thứ gì bị bỏ sót. Sau khi đã dùng Antigravity một tuần và xác nhận mọi thứ đều có ở đó, bạn có thể xóa thư mục này.

Nếu bạn dùng AGENTS.md làm cấu hình chung cho mọi công cụ AI, bạn không cần chỉnh sửa tệp đó. Antigravity CLI đọc AGENTS.md từ cùng thư mục với Claude Code hoặc Codex.

Cần thay đổi những biến môi trường nào?#

Bảng thay thế đầy đủ:

Nếu GitHub Actions của bạn truyền secrets, hãy mở Settings -> Secrets -> Actions và đổi tên các khóa. Bản thân các giá trị vẫn giữ nguyên (khóa API của Google không thay đổi trong quá trình chuyển đổi).

Kiểm tra mọi nơi có thể chứa GEMINI_:

# Find mentions throughout the project
grep -rn "GEMINI_" . --include="*.yml" --include="*.yaml" --include="*.sh" --include=".env*" 2>/dev/null

# In dotfiles
grep -nE "GEMINI_" ~/.zshrc ~/.bashrc ~/.bash_profile ~/.config/fish/config.fish 2>/dev/null

Sau khi thay, khởi động lại terminal và kiểm tra có biến mà không in bí mật. Không bật shell tracing hoặc chép giá trị khóa vào log. Có biến chưa chứng minh xác thực; xem agy doctor riêng:

if [ -n "${AV_API_KEY:-}" ]; then
    printf 'AV_API_KEY is set\n'
else
    printf 'AV_API_KEY is missing or empty\n'
fi
agy doctor        # should show “authorized”

Những gì thường gặp trục trặc khi chuyển đổi và cách khắc phục#

Danh sách kiểm tra các vấn đề ban đầu:

1. Máy chủ MCP. Nếu bạn dùng mcp_servers trong .gemini/config.json, chúng có thể không được tiếp nhận sau khi chạy agy plugin import gemini. Kiểm tra bằng agy inspect — sẽ có phần mcp. Nếu phần này trống hoặc có lỗi, hãy viết lại cấu hình thủ công bằng agy config --edit. Định dạng được mô tả trong tài liệu Antigravity chính thức (tìm phần MCP).

2. Hooks tùy chỉnh. Nếu bạn có tập lệnh bash trong .gemini/hooks/ đọc $GEMINI_API_KEY, tập lệnh đó sẽ ngừng hoạt động. Tìm những vị trí như vậy: bash

   grep -rn "GEMINI_" .agents/hooks/ 2>/dev/null
   

   Thay các biến đó.

3. CI/CD. Trong GitHub Actions hoặc GitLab CI, hãy đổi các bước sử dụng lệnh gemini sang agy. Tên tệp nhị phân trong trình cài đặt có thể khác, vì vậy hãy tạo một lớp trừu tượng bằng biến $CLI_CMD.

4. Tiện ích IDE. Tiện ích Gemini Code Assist cho VS Code sẽ bị vô hiệu hóa cùng với CLI. Công cụ thay thế là Antigravity IDE (một bản fork VS Code riêng) hoặc AGENTS.md trong bất kỳ trình soạn thảo AI nào khác.

5. Nạp bằng @[file]. Các bản Antigravity CLI đầu tiên có lỗi trong lệnh @src/file.ts dùng để nạp tệp vào ngữ cảnh. Hãy cập nhật lên phiên bản mới nhất: agy update.

Nếu có thứ gì quan trọng bị hỏng và không thể sửa trong vòng một giờ, giải pháp tạm thời cho gói Free là tiếp tục dùng Gemini CLI đến ngày 18 tháng 6, đồng thời thiết lập quá trình chuyển đổi trên một nhánh riêng của kho lưu trữ. Giới hạn thời gian: 14 ngày.

Có nên tiếp tục dùng công cụ của Google sau ngày 18 tháng 6 không?#

Có thể xem Antigravity 2.0 là lựa chọn dự phòng trong những trường hợp công cụ chính của bạn (Claude Code hoặc Codex) không phù hợp. Để tìm hiểu chi tiết ưu và nhược điểm, hãy xem hướng dẫn về Google Antigravity 2.0.

Tóm tắt nhanh việc cần làm tùy theo tình huống của bạn:

Danh sách kiểm tra chuyển đổi trong 15 phút#

1. Cài đặt Antigravity CLI

   curl -fsSL https://antigravity.google/cli/install.sh | bash (macOS/Linux) hoặc irm https://antigravity.google/cli/install.ps1 | iex (Windows PowerShell).

2. Khởi chạy agy và xác thực

   Không có đối số: agy. Chọn OAuth hoặc khóa API.

3. Nhập plugin từ .gemini

   agy plugin import gemini — lệnh này chuyển các tiện ích mở rộng toàn cục. Chạy lại trong thư mục dự án để chuyển plugin của workspace.

4. Di chuyển kỹ năng

   mv .gemini/skills/ .agents/skills/. Nội dung tệp giữ nguyên.

5. Thay biến môi trường

   Trong ~/.zshrc/~/.bashrc và các tệp .env: GEMINI_API_KEY → AV_API_KEY, GEMINI_PROJECT_ID → AV_PROJECT_ID, GEMINI_REGION → AV_REGION. Khởi động lại terminal.

6. Xác minh cài đặt

   agy doctor — cả bốn mục (tệp nhị phân, xác thực, plugin, mạng) đều phải hiển thị màu xanh.

7. Chạy thử một tác vụ

   agy "write a README for the project in the current folder" — kiểm tra xem kết quả có tương tự kết quả Gemini CLI tạo ra hay không.

8. Cập nhật GitHub Actions / GitLab CI

   Đổi tên lệnh và secrets từ GEMINI_* thành AV_*.

9. Giữ .gemini/ làm bản sao lưu

   Bạn có thể xóa thư mục này sau 1–2 tuần kể từ khi xác nhận mọi thứ hoạt động.

Cuối cùng: ngày 18 tháng 6 không có nghĩa là “mọi dự án của bạn sẽ ngừng hoạt động”. Điều đó có nghĩa là kênh miễn phí sẽ bị vô hiệu hóa. Quyền truy cập Cloud API trả phí vẫn còn, kho lưu trữ Gemini CLI vẫn còn và bạn có thể fork dự án. Nếu dùng gói Free, bạn cần quyết định trước ngày 18 tháng 6; nếu không, lần chạy gemini "something" tiếp theo sẽ trả về lỗi xác thực.