# Antigravity CLI (agy): chạy tác tử trong terminal và script

URL: https://opcaios.org/blog/antigravity-cli-agy
Ngày: 2026-11-03
Cập nhật: 2026-11-03
Tác giả: Lê Quốc Nghĩa
Chuyên mục: Hướng dẫn

Antigravity CLI là gì? Antigravity CLI là công cụ dòng lệnh của Google, gọi bằng lệnh `agy`, dùng chung tác tử, tài khoản và tuỳ biến với ứng dụng Antigravity nhưng chạy ngay trong terminal: có giao diện tương tác (TUI) để làm việc trực tiếp và có chế độ print (headless) để gọi tác tử từ script, Git hook hoặc CI. Phần giới thiệu chung đã có ở bài [Antigravity là gì?](/blog/antigravity-la-gi); bài này chỉ đi sâu vào antigravity cli. Chúng tôi không hứa CLI thay được ứng dụng desktop và không đo tốc độ hay độ chính xác; cờ và lệnh dưới đây lấy từ tài liệu chính thức và `agy --help` bản 1.4.12, đọc ngày 03/11/2026, chỗ tài liệu tự mâu thuẫn được ghi rõ. Bài đi qua cài đặt, chế độ print, nối tiếp hội thoại, chế độ chạy, CI, chuyển từ Gemini CLI và AI credits.

![Sơ đồ Antigravity CLI: cài đặt, đăng nhập, TUI, chế độ print với đầu ra JSON, nối tiếp hội thoại, chế độ chạy, quyền và sandbox, chuyển từ Gemini CLI](https://opcaios.org/images/blog/antigravity-cli-agy/so-do.webp)
*Từ cài đặt đến chạy tác tử trong script: các lớp chính của Antigravity CLI. Sơ đồ: OPCAIOS.*

## Cài đặt Antigravity CLI như thế nào?

Cài đặt Antigravity CLI dùng một script cài tự động của Google, theo trang Getting Started trong tài liệu Antigravity (đọc ngày 03/11/2026). Trên macOS, Linux và Googlebook, lệnh cài là một dòng `curl` tải `install.sh` rồi chạy bằng `bash`; trên Windows có bản cho PowerShell (`install.ps1`) và cho CMD (`install.cmd`). Kiểm tra bằng `agy --version`; lần chạy đầu, CLI hỏi có tin thư mục hiện tại không. Script cài nhận hai cờ: `--skip-aliases` để không đụng alias cũ trong hồ sơ shell và `--skip-path` để không tự thêm PATH. Về sau, `agy update` cập nhật CLI, còn `agy install` cấu hình lại PATH với cùng hai cờ cộng `--dir`. Trang /docs/install hiện là trang Authenticate: ứng dụng, CLI, tiện ích IDE và SDK dùng chung một lớp đăng nhập, nên đăng nhập ở một nơi là các nơi khác trên máy dùng được.

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

## Đăng nhập Antigravity CLI có những cách nào?

Antigravity CLI có bốn cách xác thực, theo trang Authenticate (đọc ngày 03/11/2026):

1. **Keyring cục bộ:** CLI tìm phiên trong kho khoá của hệ điều hành; không có thì mở trình duyệt để đăng nhập tài khoản Google.
2. **SSH:** CLI in một URL, người dùng mở trên máy mình, đăng nhập, rồi dán mã xác nhận lại vào terminal từ xa.
3. **Khoá Gemini API:** đặt `modelProvider` là `gemini` trong settings.json của CLI và xuất biến `GEMINI_API_KEY`. Chỉ đặt biến thì không có tác dụng, và CLI không đọc tệp `.env`.
4. **ADC của Google Cloud:** cho doanh nghiệp, bật bằng `AGY_ADC_AUTH=true`.

## Những lệnh chính của agy là gì?

Lệnh của Antigravity CLI chia ba nhóm, theo trang CLI reference và `agy --help` (đọc ngày 03/11/2026):

| Nhóm | Ví dụ | Dùng để |
|---|---|---|
| Lệnh con | `agy models`, `agy agents`, `agy mcp`, `agy plugin`, `agy update` | Xem model, tác tử, quản lý MCP, plugin |
| Cờ khởi động | `--model`, `--effort`, `--mode`, `--add-dir`, `--sandbox` | Cấu hình một phiên |
| Lệnh gạch chéo | `/plan`, `/goal`, `/rewind`, `/fork`, `/resume`, `/usage` | Điều khiển phiên đang chạy |

Chạy `agy` mở TUI ở thư mục hiện tại; trong TUI, `@` gợi ý đường dẫn tệp, `!` đầu dòng chạy lệnh terminal, `Shift+Tab` đổi chế độ. Cấu hình lâu dài nằm trong settings.json, mở bằng `/config`; cờ khởi động chỉ ghi đè cho phiên hiện tại.

## Chế độ print (headless) của Antigravity CLI hoạt động thế nào?

Chế độ print, còn gọi là headless, là cách chạy Antigravity CLI không tương tác: gửi một yêu cầu, nhận kết quả rồi thoát, theo trang Headless mode (đọc ngày 03/11/2026). Gọi bằng `-p` hoặc `--print`, `--prompt`. Câu trả lời ra stdout, còn lỗi, thông báo quyền và tiến độ ra stderr, nên gán thẳng kết quả vào biến shell được. Cờ `--output-format` có ba giá trị: `text` (mặc định), `json` (một đối tượng khi xong, gồm `conversation_id`, `status`, `response`, `duration_seconds`, `num_turns` và `usage` đếm token) và `stream-json` (mỗi dòng một sự kiện: một `init`, nhiều `step_update`, một `result`). Headless dùng phiên đăng nhập đã lưu; trong CI chưa đăng nhập, lệnh thoát với lỗi xác thực thay vì treo.

```bash
agy -p "In one sentence, what is a git rebase?" --output-format json | jq -r '.response'
```

### --json-schema và --print-timeout dùng khi nào?

`--json-schema` ép câu trả lời theo JSON Schema, nhận chuỗi schema, đường dẫn tệp `.json` hoặc tên kiểu đơn giản; kết quả đã phân tích nằm ở `structured_output`. Cách này đáng tin hơn dặn tác tử "trả JSON" rồi tự cắt chuỗi. `--print-timeout` đặt giới hạn thời gian, ví dụ `15m`. Lưu ý: `agy --help` và CLI reference ghi mặc định `0s` (chờ đến khi xong), còn trang Headless ghi mặc định chờ tối đa 5 phút. Vì tài liệu mâu thuẫn, nên luôn đặt giá trị rõ ràng trong script.

## Làm sao nối tiếp một hội thoại trong script?

Nối tiếp hội thoại trong Antigravity CLI dùng hai cờ, vì mỗi lượt headless mặc định không nhớ gì, theo trang Headless mode (đọc ngày 03/11/2026). `--continue` (viết tắt `-c`) mở lại hội thoại gần nhất, còn `--conversation <ID>` mở đúng hội thoại có ID lấy từ trường `conversation_id` của lần chạy trước. Theo trang Managing conversations, lịch sử gắn theo thư mục làm việc: chạy `agy` từ thư mục nào thì chỉ thấy phiên của thư mục đó. Mỗi lần `--continue` là một tiến trình mới. Khi cần nhiều lượt trong một tiến trình, dùng `--input-format stream-json` kèm `--output-format stream-json`: script ghi từng dòng JSON có `event: "user"` vào stdin, mỗi dòng chạy một lượt và trả về một sự kiện `result`; đóng stdin là kết thúc. Tài liệu nói cách này nhanh hơn gọi lặp `--continue`; chúng tôi chưa đo.

## --mode và --effort khác nhau thế nào?

`--mode` quyết định tác tử tự làm đến đâu, còn `--effort` quyết định model suy luận sâu đến đâu. Theo trang Choose an execution mode (đọc ngày 03/11/2026), có bốn chế độ:

1. **default:** cho xem diff trước khi sửa tệp, hỏi trước khi chạy lệnh.
2. **accept-edits:** tự duyệt sửa tệp trong workspace, vẫn hỏi trước khi chạy lệnh.
3. **auto (Preview):** tự duyệt sửa tệp, chạy lệnh trong sandbox, tự đánh giá lệnh ngoài sandbox; lệnh không đảo ngược được vẫn hỏi. Cần terminal sandbox, có từ bản 1.3.5 trên macOS, Linux và 1.4.4 trên Windows, chưa có cho tài khoản doanh nghiệp.
4. **plan:** nghiên cứu và lập kế hoạch trước khi viết mã.

Quy tắc allow, ask, deny trong `/permissions` vẫn ưu tiên hơn chế độ. Về `--effort`, `agy --help` liệt kê `low`, `medium`, `high`, `xhigh`, `max`; trang `/effort` giải thích phần lớn model chỉ có ba mức đầu. Trong headless, `--model` sai tên làm lệnh thoát mã khác 0 thay vì lặng lẽ đổi model.

## Chạy agy qua SSH, Git hook và CI cần lưu ý gì?

Chạy Antigravity CLI ngoài máy cá nhân cần giải quyết ba việc: đăng nhập, quyền và xử lý lỗi. Qua SSH dùng luồng URL và mã xác nhận; trong CI không có trình duyệt, dùng khoá Gemini API hoặc ADC. Theo trang Headless mode và CLI best practices (đọc ngày 03/11/2026), nên:

1. Dùng `--output-format json` và kiểm tra `status` bằng `jq`; chỉ `SUCCESS` là thành công.
2. Đặt `--print-timeout` rõ ràng.
3. Cho phép đúng lệnh cần bằng `permissions.allow`, không dùng `--dangerously-skip-permissions` trên máy có dữ liệu thật.
4. Cân nhắc `--sandbox`; từ bản 1.4.4, cờ này không có tác dụng nếu máy không có sandbox.
5. Ghim `--model` để kết quả không đổi khi model mặc định đổi.

Ví dụ giả định: Git hook gọi `agy -p` soạn thông điệp commit từ diff, người dùng đọc lại trước khi commit. Trang best practices có ví dụ dùng cờ `--cwd`, nhưng cờ này không có trong `agy --help` bản 1.4.12. Cách làm này gần với [codex exec](/blog/codex-exec-chay-tu-dong).

## Chuyển từ Gemini CLI sang agy thế nào?

Chuyển từ Gemini CLI sang Antigravity CLI phần lớn diễn ra tự động ở lần chạy đầu, theo trang Migrating from Gemini CLI (đọc ngày 03/11/2026): CLI hiện danh sách tài sản để chọn, chuyển token vào keyring và ánh xạ thiết lập hiển thị. Những điểm cần tự kiểm tra:

| Thứ cần chuyển | Gemini CLI | Antigravity CLI |
|---|---|---|
| Extension | Extension | Plugin, qua `agy plugin import gemini` |
| Skill của dự án | `.gemini/skills/` | `.agents/skills/` (tự đổi tên thư mục) |
| Cấu hình MCP | Trong settings.json | Tệp riêng `mcp_config.json` |
| URL server MCP từ xa | `url` hoặc `httpUrl` | `serverUrl` |
| Tệp quy tắc | GEMINI.md, AGENTS.md | Giữ nguyên |

Tài liệu ghi rõ chỉ tương thích một phần. Chi tiết về MCP và plugin có ở bài [MCP và skill trong Antigravity](/blog/mcp-va-skill-trong-antigravity); về tệp quy tắc, xem [AGENTS.md là gì?](/blog/agents-md-la-gi).

## AI credits trong CLI hoạt động thế nào?

AI credits là tín dụng dùng thêm khi hạn mức của gói đã hết, theo trang CLI AI credits (đọc ngày 03/11/2026). Thanh trạng thái hiện số credit còn lại; `/credits` mở bảng chi tiết, `/usage` hiện mức dùng hạn mức. Khoá `useG1Credits`, mặc định `false`, quyết định CLI có dùng credit khi hết hạn mức gói hay không, và không có cho tài khoản doanh nghiệp. Chúng tôi chưa đọc bảng giá credit nên không nêu giá. Với script định kỳ, để khoá này tắt thì hết hạn mức script sẽ dừng thay vì âm thầm tiêu credit.

## Kinh nghiệm của OPCAIOS

Trên máy Mac chính, chúng tôi cài CLI `agy` bản 1.4.12 song song với ứng dụng Antigravity 2.28.x, Antigravity IDE 2.5.x, Claude Code và Codex. Trong hệ thống của OPCAIOS, Antigravity là tác tử điều phối: quản lý hạ tầng, giao và theo dõi việc. Cấu hình CLI có danh sách cho phép khoảng 20 mục và vài thư mục làm việc tin cậy, thay vì duyệt tất cả; CLI có một skill trình duyệt cài thêm. Quy tắc chung nằm trong AGENTS.md, còn GEMINI.md cấp người dùng chỉ có một dòng yêu cầu trả lời tiếng Việt. Chúng tôi chưa đưa `agy -p` vào CI, chưa dùng Remote Control và chưa đo năng suất.

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

### Antigravity CLI có cần cài ứng dụng Antigravity không?

Trang Getting Started hướng dẫn cài CLI bằng script riêng, độc lập với ứng dụng desktop, và trang Authenticate mô tả một lớp đăng nhập chung cho ứng dụng, CLI, IDE và SDK. Một số bài bên thứ ba nói cần cài ứng dụng trước, nhưng chúng tôi không thấy yêu cầu đó trong tài liệu đọc ngày 03/11/2026. Trong CI, có thể dùng khoá Gemini API hoặc ADC thay vì đăng nhập tài khoản.

### Trong chế độ print, tác tử có tự chạy lệnh shell không?

Không, theo mặc định. Không ai bấm duyệt trong headless, nên công cụ cần duyệt bị "từ chối mềm": lượt chạy tiếp tục, thoát mã 0 và in thông báo ra stderr nêu tên công cụ bị chặn. Đọc, ghi tệp trong workspace được cho phép; lệnh shell chỉ chạy khi có quy tắc `permissions.allow` trong settings.json, ví dụ `command(git)`. Xem thêm [chế độ an toàn trong Antigravity](/blog/che-do-an-toan-trong-antigravity).

### Có nên dùng --dangerously-skip-permissions không?

Chỉ nên dùng trong môi trường tách biệt, có thể vứt đi như container tạm hay máy ảo, với mã và yêu cầu bạn hoàn toàn tin. Cờ này duyệt mọi lệnh, kể cả xoá tệp và gọi mạng. Cách an toàn hơn là thêm quy tắc `permissions.allow` cho đúng lệnh cần, kết hợp `--sandbox`. Xem [bảo mật khi dùng AI viết code](/blog/bao-mat-khi-dung-ai-viet-code) để chọn mức rủi ro.

### Extension Gemini CLI có chạy được trên agy không?

Phần lớn chuyển được: `agy plugin import gemini` chuyển extension cũ thành plugin, lệnh cũ thành skill và server MCP thành mục trong `mcp_config.json`. Tài liệu ghi chỉ tương thích một phần. Sau khi nhập, chạy `agy plugin list` để xem thành phần nào đã được nhận.

### Học dùng Antigravity CLI trong quy trình thật bắt đầu từ đâu?

Bắt đầu ở chế độ default trong một thư mục thử, quen với duyệt diff và `/rewind`, rồi mới sang `accept-edits` hoặc `plan`. Sau đó viết một script `agy -p` nhỏ có `--output-format json`, kiểm tra `status` và đặt `--print-timeout`. Chỉ mở rộng quyền khi đã hiểu tác tử làm gì. Muốn học có hướng dẫn cách đưa tác tử vào công việc hằng ngày an toàn, xem [khoá đào tạo ứng dụng AI](/services/dao-tao-ung-dung-ai) của OPCAIOS.

*Nguồn: tài liệu Google Antigravity tại antigravity.google/docs (getting-started, install, cli/reference, cli/using, cli/headless, cli/best-practices, cli/credits, cli/gcli-migration, cli/modes, cli/conversations, cli/commands/effort) và `agy --help` bản 1.4.12 (đọc ngày 03/11/2026); chưa kiểm chứng: mặc định thật của --print-timeout, tốc độ của stream-json, giá AI credits. Kinh nghiệm là của OPCAIOS.*