建立 2026-09-19 更新 2026-09-19

無頭模式與自動化

無頭模式（headless mode）讓 agy 不開 TUI，送出一個提示、印出結果就結束。這樣就能把代理放進 shell 腳本、CI 流程，或接到其他程式。本頁也介紹排程任務與遠端控制，讓代理在你不守著終端機時也能工作。

單次提示：-p

agy -p "git bisect 是做什麼的？"

-p（別名 --print、--prompt）送出提示後印出回應就結束。回應寫到 stdout，診斷訊息寫到 stderr，方便乾淨地擷取結果。

輸出格式

格式	用法	內容
`text`（預設）	`agy -p "..."`	純文字回應
`json`	`--output-format json`	單一 JSON 物件，含 `conversation_id`、`status`、`response`、`usage` 等
`stream-json`	`--output-format stream-json`	NDJSON：一行一個事件，即時顯示進度、工具呼叫與 token 用量

搭配 jq 取出回應文字：

agy -p "列出三種版本控制系統" --output-format json | jq -r '.response'

串流時只取文字增量：

agy -p "說明什麼是 merge conflict" --output-format stream-json | \
  jq -j 'select(.event=="step_update") | .step_update.text_delta // empty'

延續對話

agy -p "請再詳細一點" --continue                 # 接續最近一次對話
agy -p "幫我摘要" --conversation <對話 ID>        # 接續指定對話

對話 ID 可從 JSON 輸出的 conversation_id 取得。

常用旗標

旗標	說明
`-p`	執行單次提示後結束
`--output-format`	`text`、`json`、`stream-json`
`--input-format`	`text` 或 `stream-json`（從 stdin 連續輸入多輪對話）
`--json-schema`	強制結構化輸出
`--model`	指定模型
`--effort`	思考強度：`low`、`medium`、`high`
`--continue`、`-c`	接續最近一次對話
`--print-timeout`	最長等待時間，預設 `5m`
`--mode`	指定執行模式

用 agy models 列出可用的模型代號。

無頭模式下的權限

沒有人在旁邊按 y，所以需要核准的工具預設會被直接拒絕。要讓特定動作可執行，在 ~/.gemini/antigravity-cli/settings.json 明確放行：

{
  "permissions": {
    "allow": ["command(git)", "write_file(src/)"]
  }
}

不要輕易略過權限

--dangerously-skip-permissions 會自動核准一切動作，包含刪檔與任意指令。只在拋棄式的隔離環境（例如臨時容器）使用，不要在有機密或重要資料的機器上使用。

結束碼與 CI

成功回傳 0，失敗為非零，錯誤細節在 stderr 與 JSON 的 error 欄位。下面是在 CI 裡檢查結果的範例：

#!/usr/bin/env bash
set -euo pipefail

result=$(agy -p "列出三種版本控制系統" --output-format json --print-timeout 10m)

status=$(echo "$result" | jq -r '.status')
[[ "$status" == "SUCCESS" ]] || { echo "失敗" >&2; exit 1; }

echo "$result" | jq -r '.response' > output.txt

排程任務

在互動介面用 /schedule 把一段指令排成一次性計時，或週期性的 cron 任務，例如每天早上自動整理待辦。這個功能隨 2.0 一起推出，兩邊共用。

遠端控制

Remote Control 讓你從任何瀏覽器（含 iOS、Android 手機）連到執行中的桌面 App 與 CLI 對話，提示與輸出會即時同步，代理要求核准時，在終端機或瀏覽器任一邊回應都可以。有兩種模式：

模式	啟動方式	特性
互動式	在 CLI 輸入 `/remote-control`，或啟動時加 `--remote-control`	只在終端機開著時有效，關閉即斷線
常駐服務（daemon）	`agy remote-control start`	以背景系統服務執行，不需要開著終端機

常駐服務在 Linux 會隨開機啟動，macOS 在登入後啟動，Windows 需要系統管理員權限才能隨開機啟動，否則在登入後啟動。