ブラウザを入れていない環境に agy を置いたところ、最初の画面がサインインを求めてきて、そこで止まりました。GUI がないのですから当然なのですが、「ターミナル用のツールなのに、始めるためにブラウザが要る」という構図に少し引っかかったのを覚えています。
個人開発でアプリ側とサイト側を並行して抱えていると、手元の Mac だけで完結しない処理が少しずつ増えてきます。置き場所を増やしたいのに、認証がその手前で引っかかる。しばらくそういう状態でした。
8月14日の CLI 1.1.13 で、この足止めが解けました。GEMINI_API_KEY を環境変数に置くだけで、サインインを経由せず Gemini API に対して直接動かせます。
設定そのものは 5 分で終わります。ただ、手順よりも「切り替わったことをどう確かめるか」と「どのキーを渡すか」のほうが後から効いてきました。両方あわせて残しておきます。
サインインを前提にできない場所は、思っているより身近にあります
この変更が効くのは、次のような場所です。
- GUI もブラウザもない小さなサーバー。コールバック URL を開く手段がそもそもありません
- 共有マシン。自分の Google アカウントでサインインしたまま席を離れたくない場面があります
- 資格情報を個人に紐づけたくない自動実行環境。担当が変わるたびにサインインし直す構成は続きません
- ブラウザはあるのに、認証画面から戻ってこない環境。プロキシやサードパーティ Cookie の設定が絡むと起きます（この症状自体の切り分けはAntigravity の Google サインインが認証画面から戻らないときの原因と対処にまとめています）
これまでは 4 番目のケースを苦労して直すか、諦めて手元のマシンだけで使うかの二択でした。1.1.13 以降は「そもそもサインインしない」という三つ目の選択肢が増えたことになります。
設定するのは 2 箇所だけです
必要なのは、設定ファイルにモデルプロバイダを書くことと、環境変数にキーを置くことの 2 つです。
まず settings.json に次を追記します。
{
"modelProvider": "gemini"
}次に、キーを環境変数として渡します。
# 対話シェルで一時的に試す場合
export GEMINI_API_KEY="YOUR_API_KEY"
agy常用するなら、シェルの設定ファイルに置くことになります。ただし、ここで一つだけ守っていることがあります。
キーを settings.json に書かないことです。
設定ファイルは、こちらが思っている以上に外へ出ていきます。dotfiles としてリポジトリに入れ、クラウドに同期し、不具合の相談をするときにそのままスクリーンショットを撮る。環境変数なら、少なくともファイルとして持ち出される経路が 1 本減ります。
.env から読ませる構成にする場合は、値の書き方でつまずくことがあります。クォートや export の前置きの扱いはAntigravity の AI エージェントが .env ファイルの値を誤って解釈する問題の原因と対処に、そもそも読まれていない場合の伝搬経路はAntigravityのエージェントから.envが読まれないときに最初に疑うべき3つの伝搬経路にまとめてあります。
切り替わったかどうかは、起動直後の表示で分かります
設定を書いたあと、本当にキー認証で動いているのかを確かめる方法が用意されています。
起動時のバナーと /help に、使われている資格情報として「Gemini API key」と表示されます。ここがサインイン済みのアカウント名のままなら、設定ファイルの場所が違っているか、環境変数がそのプロセスまで届いていません。
そして、私が最初に誤解したのが /logout の挙動でした。
ログアウトのつもりで叩くと、セッションが終わるのではなく「資格情報は環境変数から来ている」という説明が返ってきます。一瞬「壊れているのだろうか」と思ったのですが、これは正しい動きです。環境変数由来の資格情報は、CLI 側から取り消せる性質のものではありません。抜きたいときは、こちら側で外します。
unset GEMINI_API_KEY
agy # サインインを求める従来の挙動に戻ります説明を出して何もしない、という応答は一見そっけないのですが、「どこを触れば消せるのか」を教えてくれている点で親切な設計だと思います。ログアウトできたつもりで実は消えていない、という状態が一番危ないからです。
エンドポイントを変えたいときは GOOGLE_GEMINI_BASE_URL を使います
社内のゲートウェイを通す、リージョンを固定する、といった事情がある場合は、接続先も環境変数で変えられます。
export GEMINI_API_KEY="YOUR_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://your-gateway.example.com"
agyここで一度に両方を変えると、切り分けが難しくなります。認証エラーが出たときに、キーが悪いのか、ゲートウェイが悪いのかが分かりません。まず既定のエンドポイントでキーだけを通し、動いてから GOOGLE_GEMINI_BASE_URL を足す。順番を守るだけで、原因の候補が半分になります。
制約の多いマシンという意味では、1.1.13 にもう一つ関連する改善が入っています。/codesearch が、同梱の ripgrep を実行できないときにローカル検索へ切り替わるようになりました。エンドポイント保護の製品が未署名のバイナリを止める環境では、これまで検索機能ごと使えなくなっていた場面です。管理された端末に入れる前提であれば、あわせて確認しておくとよいところです。
アプリで使っているキーを、そのまま CLI に渡さないでください
ここが、実際に運用してみて一番書き残しておきたい部分です。
私は壁紙アプリの画像分類で Gemini API を使っています。キーはすでに手元にあるので、export するだけなら 1 行です。実際、最初はそうしようとしました。
やめた理由は 3 つあります。
| 混ぜたときに起きること | なぜ後から困るのか |
|---|---|
| CLI での試行錯誤でレート制限に触れる | アプリ側のバッチ処理が同時に詰まります。原因が自分の手元にあると気づくまでに時間がかかります |
| 使用量の内訳が混ざる | 「今月伸びたのはどちらか」を後から分けられません。コストを削る判断ができなくなります |
| キーを失効させるときの巻き添え | CLI 用に発行し直したいだけなのに、アプリの処理まで止まります |
個人開発だとキーの本数を増やすこと自体が面倒に感じます。ただ、増やす手間は発行時の 1 回きりで、混ぜたときの手間は事故のたびに発生します。用途ごとに 1 本ずつ持つほうが、結果として楽でした。
目安として、私は「止まったときに困る相手が違うなら分ける」という線で決めています。アプリの処理が止まればユーザーが困ります。CLI が止まって困るのは自分だけです。困る相手が違うものを同じ 1 本に載せない、という考え方です。
キーそのものの受け渡しとログへの漏れ方まで踏み込んだ設計は、エージェントに API キーを安全に渡す — 実行時の環境変数注入とログ漏洩の遮断で扱っています。無人で走らせる構成を考えている方は、そちらもあわせてどうぞ。
サインインとキー、どちらを既定にするか
両方使える状態になったので、選び分けの基準を書いておきます。
| 状況 | 向いている方式 | 理由 |
|---|---|---|
| 手元の作業マシンで日常的に使う | サインイン | キーの管理が要らず、プラン側の枠をそのまま使えます |
| ブラウザのない環境に置く | キー | コールバックを開く手段がありません |
| 共有マシンで一時的に使う | キー | 個人アカウントの状態を残さずに済みます |
| 使用量を用途ごとに把握したい | キー | キーを分けることで内訳が分かれます |
| 人が入れ替わる環境で継続運用する | キー | 資格情報が個人に紐づかず、引き継ぎで止まりません |
私自身は、手元の Mac ではサインインのまま、それ以外の場所ではキーという分け方に落ち着きました。片方に寄せる必要はないと思っています。
次の一手
まずは使い捨てのつもりで新しいキーを 1 本だけ発行して、普段サインインで使っているマシンとは別の場所で export して起動してみてください。バナーに「Gemini API key」と出た時点で、この記事の設定は完了しています。既存のキーを流用しないことだけ、最初の 1 本から守っておくと後が楽です。