開始使用你的
agy

agy 是 Google Antigravity 家族的終端機 CLI（家族裡另有 IDE，本頁只講 CLI）。它跟 Claude Code 一樣是跑在終端機裡的 AI 工程助手，能讀寫你電腦上的檔案、執行指令。好消息有兩個：不用另外註冊帳號（用你現有的 Google 帳號登入就行），而且安裝只要一行指令。

# 1. 開「PowerShell」(不是 CMD)，貼上這行、按 Enter 安裝
irm https://antigravity.google/cli/install.ps1 | iex

# 2. 在你要工作的資料夾開終端機，啟動 agy（啟動方式見第 02 章）
agy

# 1. 開「終端機」(Terminal)，貼上這行、按 Enter 安裝
curl -fsSL https://antigravity.google/cli/install.sh | bash

# 2. 在你要工作的資料夾開終端機，啟動 agy（啟動方式見第 02 章）
agy

裝好之後，真正的開始很簡單：更新 → 啟動 → 對話。這一段把每天開工會用到的幾個指令講清楚，包含單次執行與續聊。

先決定在哪開終端機

agy 的工作範圍就是你啟動它時、終端機所在的那個資料夾（它叫這個範圍 workspace）——讀寫檔案都以這裡為基準。所以第一步是先讓終端機停在你要工作的資料夾。

開工前先更新

# 1. 先更新到最新版
agy update

啟動互動對話

更新完，在同一個終端機輸入 agy 就進入互動模式，直接打字對話。第一次啟動會要你登入授權（見第 01 章）。

# 2. 啟動 agy（工作範圍＝這個終端機所在的資料夾）
agy

單次執行：agy -p

不想進互動介面、只要它做完一件事就結束？用 -p（print 模式）：跑完把結果印在終端機、直接退出。失敗時會回傳非零的結束碼，所以特別適合寫進排程腳本（第 12 章會用到）。

# 單次執行，跑完就退出
agy -p "把這個資料夾裡的 csv 整理成一份摘要"

# 先丟一個初始任務、接著留在互動模式繼續聊
agy -i "先幫我看一下這個專案的結構"

續聊：接上上次的對話

關掉終端機不等於前功盡棄。agy 把每段對話存成 conversation，隨時接得回來：

• agy -c（--continue）：接續最近一次的對話
• agy --conversation <ID>：指定恢復某一段對話
• 貼心的是——你離開 agy 時，它會把 resume 指令印在畫面上，直接複製起來，下次貼上就回到原對話

每天要盯著終端機好幾小時，看得順眼才坐得久。這裡有兩層可以調，先搞懂差別就不會白忙：① agy 自己的深淺色、② 終端機本身的配色（你想要的任意 RGB 配色）。

① agy 的深淺色：/settings

在 agy 會話內輸入 /settings 打開設定面板，其中 colorScheme 可以切換 light／dark——讓 agy 的介面配合你終端機的底色，深底配 dark、淺底配 light，字才不會糊在背景裡。

② 終端機本身的配色（真正的自訂）

背景色、字體顏色、那套你喜歡的調色盤，全都是終端機程式在管，跟 agy 無關。在哪裡跑 agy，就去那個程式設定：

• VS Code 內建終端機：設定 → 搜尋 terminal，或用 workbench.colorCustomizations 自訂 terminal.* 顏色；整體配色跟著 VS Code 的佈景主題走
• iTerm2（macOS）：Settings → Profiles → Colors，可直接套用 Color Presets 或匯入 .itermcolors 配色檔
• Windows Terminal（Win11）：設定 → 設定檔 → 外觀 / 色彩配置，可選內建配色或在 settings.json 自訂每個顏色

＊ Windows Terminal 換色彩配置的逐步實機圖解（6 張截圖），在 Claude Code 版教學的第 03 章——那段操作純屬 Windows Terminal 本身，跟你用哪套 CLI 無關，照著做即可。

想幫 agy 加裝新能力時，最常被搞混的就是這兩個詞。一句話分清楚：Skill 是「一個能力」，Plugin 是「一包能力」。好消息是——如果你學過 Claude Code，這裡的觀念幾乎原封不動搬過來就能用。

Skill — 單一能力（一個 SKILL.md）

一個 skill 本質就是一個資料夾、裡面放一份 SKILL.md——跟 Claude Code 的 skill 是同一套慣例。放進全域的 ~/.agents/skills/<名稱>/，agy 就能載入使用；需要時它自己會用。詳見官方 skills 文件。

Plugin — 一包能力（用 agy plugin 管理）

Plugin 是更大的整合單位，一次打包一整組能力。agy 用終端機子指令管理（不是會話內的斜線指令）：

# 外掛管理：安裝 / 移除 / 列出 / 啟用 / 停用
agy plugin install <外掛>
agy plugin list
agy plugin enable <外掛>   # 或 disable、uninstall

順帶一提還有第三個擴充點：hooks——放在 workspace 的 .agents/hooks.json，讓特定事件自動觸發動作（例如改完檔自動跑檢查）。新手先知道有這東西就好，等有「每次都要手動做同一件事」的痛點再回來研究。

告訴它你要的「風格」——丟網址或截圖

做網頁時，最快讓成品貼近你心中樣子的方法，就是給它一個參考對象。你不必會講設計術語，直接給範本就好：

• 貼一個網址：把你喜歡的網站連結丟進對話框，說「我想要這種風格的網站」——agent 會參考它的版型、配色與字體調性
• 貼一份風格規則：像 Refero Styles 這類資源，把知名產品網站的設計系統整理成可讀的文字檔（DESIGN.md），複製貼給 agent，它就能照那套設計語言做——規則白紙黑字，比截圖更精準

實戰：讓它從無到有，做出一頁主題網站

用一個完整例子串起來——這裡用「教育部 AI 人才方舟計畫（簡稱 AI 方舟）」當題目，看 agy 怎麼一條龍從零幫你生出成品。你只要給主題，再在每一步幫忙確認、修正就好：

幫網頁加上動畫：anime.js 與 Lottie

先釐清一個容易混的點：skill 是裝在「agent」上的能力；而 anime.js 和 Lottie 是「前端動畫庫」——不是裝在 agy，而是引入到你的網頁裡。要讓畫面動起來就靠這兩個，引入一行、動畫邏輯交給 agy 寫。

• anime.js——做互動、進場、數字遞增這類動效。直接跟 agy 說「用 anime.js 幫這個網頁加個進場動畫」，它會把該載入的東西接好、動畫寫好
• Lottie——播放複雜的現成插畫動畫。正確流程是到 lottiefiles.com 挑現成的 .json 檔，丟給 agy 說「把這個 Lottie 放到網頁上」——別叫 agent 手寫 Lottie，它是「複雜動畫的播放器」，不是拿來自己刻的

網頁在你電腦上做好了，怎麼讓別人也能打開？這一步叫「部署（deploy）」——把檔案放上一個會給你公開網址的服務。對新手最友善、又免費的選擇是 Vercel。而且整個過程不用你動手，交給 agy 就好。

讓 agy 自己裝好工具

部署要用到 Vercel CLI（一個命令列工具），但你不必先自己去裝。直接跟 agy 說「幫我把這個網頁部署到 Vercel」，它會自己把工具裝起來、帶你登入、再完成部署。背後跑的大致是這幾行：

# 1. 安裝 Vercel CLI（agy 會自己跑，你不用先裝）
npm install -g vercel

# 2. 第一次要登入（會跳出瀏覽器授權，用 GitHub / Email 都行）
vercel login

# 3. 在網頁專案資料夾裡部署
vercel          # 產生一個預覽網址
vercel --prod   # 正式上線到你的主網址

跑完它會回給你一個 https://你的專案.vercel.app 的網址，丟給任何人都能打開。

兩條路：直接上傳，還是先過 GitHub？

同樣是上線，有兩種做法，差在你要不要版本紀錄與自動更新：

＊ 另一個熱門選擇是 Cloudflare Pages——免費額度更大、流量大或想長期省成本時很適合，同樣能連 GitHub 自動部署，只是上手沒 Vercel 那麼順。新手想最快看到成果，先用 Vercel 就好，之後再依需求評估。

順帶認識：agy 的 Artifacts（產出物）

agy 工作時，不是只會回你一段話——過程中產出的計畫、報告、比較表這類成果，會存成 artifact（產出物），收在它的全域資料目錄（~/.gemini/antigravity-cli/ 底下）。agy 有內建的 artifact 檢視器可以翻閱這些產出物，而且支援搜尋：按 / 輸入關鍵字，再用 n／N 在結果間往下／往上跳——長報告找重點特別快。

每次開新對話，agent 的記憶都是一片空白。要讓它跨對話記住你的規則，靠的是一個放在 workspace 根目錄的純文字檔——在 agy 這裡，它叫 GEMINI.md 或 AGENTS.md（擇一即可），啟動時會自動讀進記憶。把「希望它每次都遵守的規則」寫進去，它就不會每次都要你重講。

GEMINI.md 還是 AGENTS.md？怎麼選

該寫什麼進去？

官方最佳實踐建議寫這幾類：目錄結構規範（什麼放哪）、程式風格與慣例、測試指令（怎麼驗證改動沒壞）、棄用注意（哪些舊東西別再碰）。對一般使用者來說，就是「每次都要重講的規矩」通通收進來。

全域資料放哪？

除了 workspace 裡的規則檔，agy 自己的全域資料都收在 ~/.gemini/antigravity-cli/：

• settings.json — 你的偏好設定（/settings 面板改的東西存這裡）
• conversations — 對話紀錄（agy -c 續聊靠它）
• brain — 產出物（artifacts，見第 05 章）
• knowledge — 累積的知識

第一天，該寫什麼進 AGENTS.md？

很多新手一裝好就想把規則寫好寫滿——其實不必硬擠。你還不知道自己的使用習慣，寫一堆用不到的，每次啟動都吃 context、還可能互相打架。但有三件小事值得第一天就設，因為馬上省事：

• 語言：「一律用繁體中文、台灣用語回我」——不然它常回英文或簡體
• 風格：「回答先講重點、別長篇大論」——省你讀字、也省 token
• 你是誰：「我是國小老師／資訊組長，舉例盡量貼近教學、校園情境」——給的範例更對味

一句話交辦就好，例如：

# 跟 agy 說
在這個 workspace 建一份 AGENTS.md 並記進去：①一律繁體中文台灣用語
②回答先講重點別長篇 ③我是國小老師，舉例貼近校園情境

真實案例：規則檔讓它「自動照規矩做事」

一個校園網路管理的實例，看規則檔怎麼省下「每次都要重講規則」的工：

平常在一個資料夾裡，放著日常網路盤點的檔案——全校 IP 配置表（CSV）、網管交接記憶（md），還有一份 AGENTS.md，裡面寫好配發原則（例如：避開保留位址與網段的頭尾、優先給連續空號）。

某天衛生所行動醫院臨時來要 4 個空的 IP。打開 agy，只說一句「行動醫院需要 4 個空的 IP，幫我找出來、做一張可列印的配置表」——它就讀 CSV 比對出未配發的 IP、自動依 AGENTS.md 的配發原則挑掉頭尾、選出 4 個，再產出一張可直接列印成 A4 的 HTML 配置表。

agy 的最大賣點：三家模型一池混用

大多數 agent CLI 只能用自家模型；agy 特別的地方是——除了 Google 自家的 Gemini，還能直接切到 Anthropic 的 Claude、以及開源的 GPT-OSS，一個工具、三家模型隨你調度。在終端機跑 agy models 可以列出目前可用清單（下表為 v1.1.1 實測）：

怎麼切換

兩個入口：啟動時用 --model 旗標指定這次 session 用哪顆；會話中用 /settings 打開設定面板切換。

# 啟動時指定模型（名稱要含思考強度、加引號）
agy --model "Gemini 3.5 Flash (High)"

# 查目前有哪些模型可用
agy models

agent 在一次對話裡，會把整段聊天記錄都放在它的「context 視窗」（短期記憶）。對話越長，這個視窗越滿——回應變慢、也容易被舊脈絡干擾。所以「適時開新對話」是用得順不順的關鍵。

換任務，就開一段新對話

agy 的對話以 conversation 為單位。當你切換到不相關的新任務時，最乾淨的做法是：退出目前的 agy、重新啟動——就是一段全新的 conversation，context 從零開始。留著上一個任務的舊內容只會拖慢速度，又容易讓它被無關脈絡帶偏。

舊對話不會不見：續聊機制

「重啟就是新對話」聽起來很可怕？不會——每段 conversation 都存在 ~/.gemini/antigravity-cli/ 裡，隨時接得回來：

# 接續最近一次對話
agy -c

# 恢復指定的某段對話（離開時畫面上會印好 resume 指令，複製即可）
agy --conversation <ID>

所以正確心態是：一個任務一段 conversation。做 A 專案開一段、做 B 專案開一段；哪段要接著做，就用它的 ID 恢復——比「一段對話從頭聊到尾」乾淨得多。

收尾習慣：離開前把進度寫進 AGENTS.md

還有一個跨對話保險：conversation 存的是對話，但「這個專案做到哪、決定了什麼」這種狀態，最可靠的落點是第 06 章的 AGENTS.md。要結束一段工作前，跟它說一句：

# 收尾的正確順序
把這次的進度、決定和待辦，整理寫進這個專案的 AGENTS.md
# 然後再退出——下次不管開新對話還是續聊，規則檔都會自動載入

Obsidian 是一款本機優先的筆記軟體：你的筆記就是電腦上一個資料夾裡的一堆 .md 純文字檔（這個資料夾叫 Vault 庫）。把筆記、記帳、行程、靈感都收進來，就是你的「數位大腦」。

安裝：直接叫 agy 幫你裝

Obsidian 本體是個 app，到 obsidian.md 下載就行（三平台都有、個人免費）。但更省事的作法是——在終端機跟 agy 說一句「幫我安裝 Obsidian」，它會用你系統的套件管理器（Windows 的 winget、macOS 的 brew）裝好。這正是終端機 agent 的精神：能用講的，就別自己一步步點。

規劃結構：用「討論」的，不用一個個點設定

Vault 說穿了就是一個資料夾。與其在設定選單裡點來點去，不如在你想當數位大腦的資料夾開終端機、啟動 agy，直接跟它討論你要的結構，它就幫你建好。例如：

# 跟 agy 說（自然語言就好）
幫我把這個資料夾規劃成我的數位大腦：
最上層分「生活」「工作」兩大類，再建一個 attachments 放所有附件。
生活底下分財務、健康、隨筆；工作底下分系統管理、會議。

交給 agy 操作

把 Vault 準備好之後，在這個資料夾啟動 agy，你的數位大腦就接上 AI 了。常見玩法：

• 記帳：把帳單照片丟進 attachments，請它讀出金額、填進你的 markdown 記帳表
• 整理：請它把散亂的筆記分類、加標籤、建索引、找出重複內容
• 產出：請它讀某個主題的筆記，彙整成一篇文章、簡報，甚至像這頁一樣的網頁

最後收幾個讓你用得更快、更安心、更順手的小技巧。

agy --dangerously-skip-permissions

當你開始信任終端機 agent，下一步是讓它不關機——跑在一台全天開著的機器上，變成隨時待命的個人助理。agy 對這個玩法特別友善：SSH 登入流程是官方內建的（見第 01 章），VPS 上裝起來毫無障礙。

① 部署在 VPS 或 Mac mini，全年無休

把 agy 裝在一台不關機的機器上，它就能 24 小時待命：

• 選一台常開的機器：雲端 VPS（如 Hetzner、DigitalOcean、Linode，月費約幾美金）或家裡一台 Mac mini／迷你主機——省電、安靜，適合擺著長跑
• 用排程(cron)＋agy -p 讓它自動做事：每天早上自動整理摘要、定時抓資料產報告。-p 跑完就退出、失敗回非零結束碼，排程腳本能直接判斷成敗——天生適合自動化（實例見第 12 章）
• 規則寫死在 AGENTS.md：時區、輸出格式、哪些事絕對不能碰——半夜自動跑時才不會走鐘（見第 06 章）

② 調度子代理：--agent

agy 支援子代理（subagent）分工——不同角色的 agent 各司其職，而且支援巢狀的子代理樹（子代理還能再派子代理）。用 agy agents 列出目前可用的 agent，啟動時用 --agent 指定這次 session 由哪隻出馬：

# 列出可用的 agents
agy agents

# 指定某隻 agent 跑這次 session
agy --agent <名稱>

③ 多代理交叉查核：雙驗 / 三驗

單一 AI 難免有盲點或幻覺。進階玩法是把同一個問題派給多隻不同家的 Agent 各自獨立作答、再交叉比對——用「會議室裡多人覆核」取代「單人說了算」。agy 在這局裡是很好的一角：它背後是 Gemini 系模型，跟 Claude Code（Claude）、Codex（GPT）正好三家不同腦袋。

• 雙驗：同一道題同時丟給兩個不同廠牌的 Agent（例如 Claude Code＋agy），兩邊互不看對方答案各自查證，再並列出一致處與分歧處
• 三驗：Claude Code＋Codex＋agy 三方獨立作答，標出「三方一致 / 兩方同意一方異議 / 三方各異」，可信度更高
• 鐵律是「盲測」：誰都不先看別人的答案，避免互相帶風向；對任何分歧、或只有一方提到的主張，一律再主動查證後才下定論（單方提及 ≠ 就是幻覺）

最後把前面的零件組起來用：agy -p（單次執行）＋ cron（排程）＋ AGENTS.md（鐵則）＝一條全自動的每日任務線。以「每天早上自動產出一份晨間摘要」為例：

agy -p "讀這個資料夾的 notes/，把昨天新增的內容整理成一份晨間摘要，存到 daily/今天日期.md"

學 agy 與 AI Agent 一路上會反覆撞到這些詞，這裡用一句白話講清楚（前面章節提過的也收進來，方便回查）。