--- title: agy をヘッドレスで動かす description: Claude のクォータを投入する代わりに、Antigravity（agy）アカウントへ作業を振り向けます。 section: Guides order: 2 --- # clikae で agy（Antigravity）をヘッドレスで動かす 特定の一つの仕事に絞ったレシピです。**メインの Claude/codex クォータを投入する代わりに、 Antigravity（agy）の Pro アカウントへ作業を振り向ける** こと。agy は本物の有料エンジン です — 使いましょう。ただし `claude -p` / `codex exec` とは挙動が違い、無駄になる agy クォータの大半は、間違った動かし方から生まれます。このページは、毎セッション学び直して （そして使い潰して）しまわないための、決定版の手順書です。 > 要点 — agy は **グローバル、単一アカウント、burn 不可** です。これは「使えない」という > 意味では **ありません**。意味するのは、`burn` が claude/codex でやるようにタンクをまたいで > 自動で再ルーティングできない、ということです。`clikae agy -- -p` で *アクティブな* > アカウント上でヘッドレスに動かし、バッチの合間に対話的にアカウントを切り替えます。 ## 押さえるべき一つの事実 agy の Google ログインは、シェルごとの環境変数ではなく **グローバルな Keychain エントリ 1 つ** です。したがって、 - **`clikae env agy` は存在せず**、**シェルごとのルーティングもありません** — `clikae env agy` はわざと失敗し、あなたをここへ案内します。 - `clikae agy ` は `~/.gemini`（とそのログイン）を **マシン全体で** 入れ替えます — agy アカウントは一度に *すべての* ターミナルで 1 つだけアクティブになります。並列ではなく 排他です。 - `clikae burn` は予備タンクの巡回に agy を組み込めません（同じマシン上では再ルーティング する *先* がありません）。agy のリレーは **手動で、逐次** です。バッチを走らせ、タンクを 切り替え、次を走らせる。同一アカウントの agy↔gemini がなぜ偽のリレーになるか（同じ クォータのバケツ）は、`agy-gemini-shared-quota` のメモを参照してください。 ## 決定版のヘッドレス呼び出し ```bash # agy をタンクに切り替え（マシン全体）、そのアカウント上でヘッドレスに走らせる。 # プロンプトは FILE 経由で渡す — 段落をシェルでクォートした -p '…' に詰め込まないこと。 clikae agy -- \ --print-timeout 900s \ --add-dir /abs/path/to/repo `# タスクが cwd 外のファイルを読み書きする場合のみ` \ -p "$(cat /tmp/agy_prompt.txt)" ``` これだけです。以下のルールが、本物の成果が返るか、空振りが返るかの分かれ目になります。 ## agy を空振りさせないためのルール（苦労して得た教訓） 1. **ヘッドレスの agy は `-p`（print モード）であって、`-i` ではない。** `agy -i` は本物の TTY を必要とし（bubbletea の TUI です）、ヘッドレスでは `could not open TTY` で死にます。 エージェント主導やバックグラウンドの呼び出しは、すべて `-p` を使います。 2. **プロンプトはネストしたクォートではなく、ファイル経由で渡すこと。** `-p "$(cat /tmp/foo.txt)"`。ネストした `sh -c '… -p "…"'` のクォートはプロンプトを 黙って食い、agy は的外れな答えを返します。一層で、ファイルから。 3. **大きな出力を stdout から集めない — agy にファイルを書かせること。** `agy -p` の stdout での返却は、大きい／構造化された出力では信頼できません。プロセスは 0% CPU で 生きたまま、**すべてをバッファに溜めて何も出さない** ことがあります。大きいものは、 agy に *結果をファイルへ自分で書かせ*（エージェント的に）、そのファイルを読んでください。 置き場所: `~/.gemini/antigravity-cli/brain//*.md` — `-p` の stdout は、 多くの場合そこへの 1 行ポインタにすぎません。 4. **死んだタスク、固い境界、長いタイムアウトを与えること。** agy の対話時の強み — 自由な探索 — は、ヘッドレスでは負債になります。あてどなくさまよい（たとえば git diff を 調べに行く）、何も書かないままタイムアウトを使い切ります。プロンプトで明示的に柵を 立て（「git を見るな、調査するな、X だけをやって Y を書け」）、`--print-timeout 900s` を 与えてください（既定の約 5 分は、本物の仕事には短すぎます）。 5. **macOS に `timeout` はない。** `--print-timeout` はいつもきれいに kill するとは 限りません。無人ジョブでは、外側に固いキル（たとえば Python の `subprocess.run(..., timeout=N)`）を保険として巻いてください。 6. **タンクを切り替える前に `pkill -9 -f "agy -p"`。** `clikae agy ` は、`agy` プロセスが生きている間は切り替えを拒みます（その下で `~/.gemini` を入れ替えると セッションが壊れます）。古い／ハングした print ジョブを先に kill してください。 7. **cwd 外のファイルを読むには `--add-dir ` が必要**（事前認可）です。 あるいは純粋なテキストを stdin で流せば（`cat file | agy -p "…"`）、ツール／権限の ゲートに当たりません。認可されていないパスを読もうとする素の `agy -p` は、答える TTY の ない権限プロンプトを待って **永遠にハングします**。 8. **`--dangerously-skip-permissions` は *人間* 用であって、エージェント用ではない。** clikae が *別の AI*（たとえば Claude Code）に *動かされている* とき、その AI の安全 分類器は、`Bash(agy:*)` の許可ルールがあっても、`--dangerously-skip-permissions` を 伴う agy 呼び出しをブロックします。素の `agy -p`（skip フラグなし）なら通ります。 どうしても skip-permissions が要るタスクなら、その行は人間が走らせます（たとえば `!` 接頭辞で）。エージェントに自己認可を期待しないでください。 9. **バッチごとにタンクを回し、週上限を分散させること。** グローバルアカウントが 1 つ＝ 逐次実行。タンクを交互に使えば（`clikae agy 8` / `clikae agy c` / …）、使用量を複数の アカウントに分散できます。正味のスループットはラウンドロビンであって、並列ではありません。 ## agy が本当に得意なヘッドレス作業 - **一発のテキスト生成** — 翻訳、トランスクリエーション、要約、コピー。検証済み: スコープの 明確なテキストタスクなら、単発の出力を確実に生み出します。（zh-TW を台湾の語感で レビューさせるときは、大陸→台湾の用語ルーブリックを添えてください — agy は中身が Gemini なので、放っておくとブレます。ネイティブの耳ではなく、明示的なルーブリックを 与えられた採点者として扱ってください。） - **ライブ Web の QA** — agy には `read_url_content` ツールがあり、本当にブラウズします （URL を取得し、リンクをたどり、HTML を読みます）。バイヤージャーニー／i18n／仕上げの 一掃に向いており、観点ごとに 1 つのレポートファイルを出します。一度スモークテストして （ページの本物の `

` を返させて）、当て推量でないことを確かめてください。素の 生存確認なら `curl` のほうが確実です — 「サイトは生きてる？」に agy のクォータを 使わないでください。 - **メイン予算からオフロードした大きなファイル書き込みジョブ** — まるごと一つの翻訳辞書を、 ファイルに書き（ルール 3）、agy のバケツで、あなたの Claude 予算には触れずに。これが コストを意識したルーティングの見返りです。 - **`clikae conduct` での安価な幅出しレッグ** — `conduct --leg agy/` は、読み取り 専用の監査／分析プロンプトを claude/codex のレッグと並べて agy にも振り、各レッグの 出力をあなたに渡して判断させます。agy は安価で速いので、best-of-N に追加の視点として 好適です。注意: agy レッグは **現在アクティブな** agy タンク上でのみ走ります（別の タンクを指定したレッグは、実行されずに報告されます — clikae は agy を並列に切り替え られません）。その切れ状態は stdout ではなく `cli.log` から読みます。 ⚠️ **agy のレビュー提案は仕分けが必要です。** すでに決まっている製品上の判断に反することを、 自信たっぷりに勧めてきます。agy のレビューの修正を自動適用しては絶対にいけません — オーケストレーターか人間がふるいにかけます。 ❓ **未検証（慎重に扱うこと）:** ある観察は、`agy -p` が `claude -p` / `codex exec` のような 完全に自律的な複数ステップの *ファイル編集* ループを走らせない可能性を示唆しています — 単発で答えるか、非同期のビルドに委ねて返ってくるかもしれません。単発のテキスト出力は 確認済みですが、エージェント的な「編集して検証する」ループは未確認です。agy を `burn` スタイルのコード編集ワーカーとして使うつもりなら、まず制御されたタスクで検証してください。 最新の地に足のついた事実は `agy-gemini-shared-quota` を参照してください。 ## あわせてどうぞ - `docs/orchestration.md` — ヘッドレス振り分けの一般的な手引き（burn/conduct/legs）。 - `docs/dogfood-agy-headless.md` — このレシピの元になった、生のドッグフーディング日誌。 - `clikae agy --help` — agy タンクの切り替え／管理のコマンドインターフェース。