Antigravity CLI (agy) trên máy chủ

Từ ngày 18/6/2026, Gemini CLI không còn phục vụ tài khoản cá nhân miễn phí, Google AI Pro hay Ultra. Thông báo của Google hướng những người dùng này sang Antigravity CLI, tức agy. Trên máy chủ, những phần cần lưu ý là đăng nhập khi không có trình duyệt, chọn giữa đăng nhập Google và API key, và hiểu cách agy xử lý quyền khi không có ai ngồi trước terminal. Dưới đây là từng phần theo thứ tự.

Cài đặt agy

Trên Linux hoặc macOS, bằng user thông thường (không phải root):

curl -fsSL https://antigravity.google/cli/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"   # if ~/.local/bin isn't on PATH yet
command -v agy

Trang cài đặt chính thức cho biết file binary được đặt ở ~/.local/bin/agy và hỗ trợ macOS, Linux và Windows. Trình cài đặt tải bản build riêng cho từng nền tảng, với bản Linux cho cả amd64 lẫn arm64, nên VPS ARM vẫn dùng được. Hãy thêm dòng PATH vào ~/.bashrc hoặc ~/.profile để các shell và cửa sổ tmux mới đều nhận được.

Một điểm riêng cần để ý trên máy chủ: agy tự cập nhật ở chế độ nền. Trên laptop thì tiện. Nhưng trên một máy bạn để chạy liên tục, điều đó có nghĩa là phiên bản có thể thay đổi ngay giữa một phiên dài. Maude ghim phiên bản mà nó cài và tắt tính năng này bằng AGY_CLI_DISABLE_AUTO_UPDATE=1. Nếu bạn muốn sự ổn định tương tự, hãy export biến này trong shell hoặc unit khởi chạy agy.

Đăng nhập qua SSH

Chạy agy trong một phiên SSH và chọn đăng nhập Google. Trên laptop, nó sẽ mở trình duyệt. Qua SSH, nó nhận ra phiên từ xa và in ra một URL ủy quyền. Sau đó:

1. Sao chép URL và mở nó trên điện thoại hoặc laptop.
2. Đăng nhập bằng tài khoản Google bạn dùng cho Antigravity.
3. Sao chép mã mà trang hiển thị và dán trở lại terminal.

Thông tin đăng nhập được lưu trong keyring của hệ điều hành, trên Linux là Secret Service. Một VPS trống không có phiên desktop nào để mở khóa keyring. Một issue trên GitHub gửi cho agy 1.0.0 báo lỗi vòng lặp đăng nhập trên Linux headless do chính nguyên nhân đó, kèm một lỗi múi giờ ở cơ chế lưu dự phòng bằng file. Cách khắc phục của người báo lỗi là GEMINI_FORCE_FILE_STORAGE=true TZ=UTC agy …. Chúng tôi chưa xác nhận được các phiên bản hiện tại có còn cần cách này hay không. Nếu agy bắt bạn đăng nhập lại mỗi lần khởi chạy, hãy xem issue đó trước tiên. Nếu không, hãy dùng chế độ API key.

Để đăng xuất và xóa hồ sơ đã lưu, chạy /logout bên trong agy.

Chế độ API key khi chạy headless

Với CI, máy dùng chung, hay bất kỳ máy chủ nào bạn không muốn giữ phiên đăng nhập Google, hãy chạy agy bằng Gemini API key. Tài liệu cài đặt đưa ra hai bước. Đầu tiên, đặt model provider trong ~/.gemini/antigravity-cli/settings.json. Nếu file đã tồn tại, hãy gộp vào:

{
  "modelProvider": "gemini"
}

Sau đó cung cấp key cho tiến trình:

export GEMINI_API_KEY="…"   # e.g. in ~/.profile, or an EnvironmentFile for a systemd unit

Cách này bỏ qua hoàn toàn việc đăng nhập tài khoản. Mức dùng được tính phí theo token theo bảng giá Gemini API thay vì trừ vào gói Google AI. Đừng để key lọt vào lịch sử shell hay vào repository mà agent đang làm việc.

Quyền khi không có ai theo dõi

Đây là hành vi trên máy chủ khiến nhiều người bất ngờ nhất. Trong thử nghiệm của chúng tôi trên agy 1.2.14, các lần chạy headless (agy -p …, hoặc chế độ stream-json) không thể dừng lại để hỏi trước khi chạy một công cụ. Lệnh hoặc thao tác ghi file nào cần quyền sẽ bị từ chối, và kết quả của lượt đó liệt kê nó là bị từ chối. Bạn có ba cách để cho công việc đi qua:

• Quy tắc cho phép. agy đọc chúng từ permissions.allow trong ~/.gemini/antigravity-cli/settings.json. Các mục có dạng "command(npm test)", "write_file(src/app.ts)" hoặc "command(*)". Chúng được đọc khi khởi động.
• Chế độ. --mode accept-edits tự động phê duyệt việc sửa file, nhưng lệnh vẫn bị từ chối. --mode plan chỉ lập kế hoạch mà không thực hiện.
• Không kiểm tra gì cả. --dangerously-skip-permissions, dành cho máy dùng xong là bỏ. Hãy đọc chạy agent với toàn quyền một cách an toàn trước khi dùng đến nó.

agy chạy tương tác trong terminal, và Remote Control (bên dưới), có thể tạm dừng để hỏi. Vì vậy giới hạn này chỉ áp dụng cho việc chạy headless bằng script.

Mang cấu hình Gemini CLI sang

Hướng dẫn chuyển đổi đề cập đến việc này. Tóm tắt cho máy chủ đã cài Gemini CLI từ trước:

• Lần khởi chạy đầu tiên sẽ đề nghị chuyển đổi. Nếu agy tìm thấy cấu hình Gemini CLI có sẵn, nó hiển thị một danh sách các extension và cài đặt toàn cục để chuyển đổi.
• Extension trở thành plugin. Chạy agy plugin import gemini bất cứ lúc nào để chuyển extension của Gemini thành plugin của Antigravity.
• File ngữ cảnh dùng được nguyên trạng. GEMINI.md (trong workspace và ~/.gemini/GEMINI.md) và AGENTS.md được đọc mà không cần thay đổi.
• MCP server cần sửa một chút. Server toàn cục nằm trong ~/.gemini/config/mcp_config.json, server của workspace nằm trong .agents/mcp_config.json. Đổi tên các key cũ url/httpUrl thành serverUrl.
• Skill phải chuyển chỗ. Skill của workspace chuyển từ .gemini/skills/ sang .agents/skills/, còn skill toàn cục sang ~/.gemini/antigravity-cli/skills/. Bạn phải tự di chuyển chúng.

Google cho biết hiện chưa có đầy đủ tính năng tương đương, và hướng dẫn chuyển đổi lưu ý rằng một số theme tùy chỉnh và tinh chỉnh giao diện không được chuyển sang. Nếu quy trình làm việc của bạn phụ thuộc vào một extension cụ thể, hãy thử nó sau khi import rồi mới xóa cấu hình cũ.

Daemon Remote Control và Maude

Google cung cấp một cách chính thức để truy cập agy từ thiết bị khác. Theo tài liệu Remote Control, bạn có thể khởi động nó theo ba cách:

• /remote-control bên trong một phiên đang chạy. Đường hầm kết thúc khi phiên CLI đó thoát.
• agy --remote-control khi bạn khởi chạy một phiên. Đường hầm này cũng kết thúc khi phiên thoát.
• Daemon headless: agy remote-control start --name my-vps, cùng với agy remote-control status và agy remote-control stop. Nó đăng ký một dịch vụ hệ điều hành chạy liên tục ở chế độ nền.

Bạn điều khiển nó từ một bảng điều khiển web trên trình duyệt bất kỳ, đăng nhập bằng cùng tài khoản Google. Tài liệu cho biết bạn có thể cài bảng điều khiển này lên màn hình chính của điện thoại để nhận thông báo đẩy, và có thể trả lời yêu cầu cấp quyền từ terminal hoặc từ giao diện từ xa. Tài liệu cũng cho biết một feature flag ở cấp tài khoản hoặc tổ chức có thể chặn tính năng này.

Nếu Antigravity là agent duy nhất bạn dùng và feature flag đã được bật cho tài khoản của bạn, daemon chính thức rõ ràng là lựa chọn nên thử trước. Nó miễn phí, và có thể hỏi trước khi hành động.

Chạy từ điện thoại

Nếu bạn muốn chạy agy trên máy chủ cùng các agent khác và điều khiển bằng một ứng dụng gốc, Maude là một lựa chọn. Thêm máy chủ, và ứng dụng sẽ cài agy ở phiên bản đã kiểm thử rồi đăng nhập cho bạn ngay từ điện thoại. Bạn có thể đăng nhập Google bằng mã dán vào hoặc dùng Gemini API key. Nói thẳng về Antigravity trong Maude: vì Maude điều khiển agy ở chế độ headless, nó không thể dừng lại để hỏi trước khi chạy một công cụ. Maude cho bạn xem thao tác bị từ chối, và nếu bạn phê duyệt, nó thêm một quy tắc cho phép rồi thử lại. Trang agent Antigravity có thông tin chi tiết. Bản thân thay đổi của Gemini CLI, và những lựa chọn khác mà mọi người đã chuyển sang, được trình bày trong bài viết của chúng tôi về việc Gemini CLI ngừng hoạt động.

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

Những gì đã thay đổi

• 1 tháng 10, 2026 — Xuất bản lần đầu. Thông tin về cài đặt, xác thực, chuyển đổi và Remote Control được đối chiếu với tài liệu trên antigravity.google; hành vi về quyền khi chạy headless lấy từ thử nghiệm của chính chúng tôi trên agy 1.2.14.