個人開発で使っているビルド用の Linux 機へ Zed のリモート接続でつなぎ、エージェントパネルで Antigravity の新しいスレッドを開いた夕方のことです。ステータスは「サインイン中」のまま進まず、手元の iMac のブラウザには何も開きませんでした。
SSH 先のターミナルで agy を打つと、ふだんどおりに動きます。同じ機械、同じアカウントなのに、エディタ経由だけが入れない——その食い違いに、私は十五分ほど手が止まっておりました。
原因は設定の書き間違いではなく、サインインを「どの機械で、どの順番で」済ませるかという段取りの問題でした。同じところで止まっている方に向けて、見分け方から順に書き残します。
まず症状を見分ける:認証で止まっているのか、起動で落ちているのか
リモートの Zed で Antigravity が使えないとき、症状は大きく二つに分かれます。ここを取り違えると、直す場所がまるで違ってきます。
| 見えている症状 | 止まっている段階 | 最初に見る場所 |
|---|---|---|
| パネルがサインイン待ちのまま進まない。ログに「Credentials missing or invalid. Launching browser login flow...」 | 認証(OAuth のブラウザ遷移) | この記事の手順 |
| リクエストが「Authentication required」(code -32000)で失敗する | 認証(資格情報が見つからない) | この記事の手順 |
| パネルを開いた直後に「Server exited with status exit status: 255」 | 起動(プロセス自体が落ちている) | agy のパスとホスト側のユーザー解決 |
三つ目の exit 255 は、OS Login を使うクラウドの Linux 機などで報告されている別の問題です。認証の手順をいくら整えても直りませんので、先に切り分けておいていただければと思います。
前の二つに当てはまるなら、この先の手順がそのまま使えます。
なぜ SSH 越しだと戻ってこないのか
Zed はリモート接続のとき、agy acp を SSH 先の機械で子プロセスとして起動します。資格情報がなければ、agy acp は OAuth のためにブラウザを開こうとします。
ところが、そのブラウザを開こうとしているのは SSH 先の機械です。画面のないサーバーではブラウザが開かず、開けたとしても手元の私からは見えません。サインインの完了を待つ処理だけが残り、パネルは永遠に待ち続けることになります。
ターミナルの agy が平気だったのは、対話セッションならリモート環境を検出して、URL を表示し、コードを貼り付けてもらう手動の流れに切り替えてくれるからです。一方で、エディタの裏で動く agy acp は、その対話の場を持っていません。
要するに、サインインは「人が画面を見ている場所」で先に済ませ、エディタにはその結果だけを使わせるのがいちばん確実です。公式の ACP ガイドも、agy acp は対話セッションでキャッシュした資格情報を再利用する、という前提で書かれています。
直し方:SSH 先で agy acp --login を一度だけ実行する
手順は短く済みます。Zed とは別に、ふつうのターミナルから SSH 先へ入って作業します。
- 手元のターミナルから SSH 先へログインします。
agy acp --helpが通るか確かめます。通らなければ ACP を含まない古い版です。agy acp --loginを実行します。表示された URL を手元のブラウザで開き、サインイン後に出るコードをターミナルへ貼り付けます。- 完了したら Zed のエージェントパネルで新しいスレッドを開き直します。
--login はサインインだけを行って終了するフラグで、SSH 越しでも動くと明記されています。対話の agy で一度サインインしておく方法でも同じ結果になります。
あわせて、Zed 側の設定も少しだけ整えておくと、次に止まったときの手がかりが増えます。
{
"agent_servers": {
"Antigravity": {
"type": "custom",
"command": "/home/YOUR_USER/.local/bin/agy",
"args": ["acp", "--log-file", "/tmp/agy-acp-zed.log"]
}
}
}command を絶対パスにしているのは、エディタが起動するプロセスはログインシェルの PATH を読まないことがあるためです。パスは SSH 先で which agy を打って確かめた値に置き換えてください。--log-file は、ログの置き場所を自分で決めておくための指定です。
確かめる:SSH 先で動かす小さな点検スクリプト
一度直ったあとも、資格情報の期限切れや版の入れ替えで、同じ症状がまた出ることがあります。私は毎回同じ順番で確かめたかったので、SSH 先に次のスクリプトを置いて使っております。
何を解決するかというと、「agy が見つかるか」「ACP を含む版か」「直近のログに認証の失敗が出ているか」を一度に確かめ、次にやることを一行で示すことです。
#!/usr/bin/env bash
# acp-auth-check.sh — SSH 先で実行する。Zed から agy acp が入れないときの切り分け用
set -u
AGY="$(command -v agy || true)"
if [ -z "$AGY" ]; then
echo "NG: agy が PATH にありません。インストール先を確認し、Zed の command に絶対パスを書いてください"
exit 1
fi
echo "OK: agy = $AGY"
if ! "$AGY" acp --help >/dev/null 2>&1; then
echo "NG: この版の agy は ACP を含んでいません。更新してから再試行してください"
exit 1
fi
echo "OK: agy acp が使えます"
# 公式の既定ログ置き場と、Zed 設定で指定した置き場の両方から最新を拾う
LATEST="$(ls -t "$HOME"/.gemini/antigravity-cli/log/acp-*.log /tmp/agy-acp-zed.log 2>/dev/null | head -1)"
if [ -z "$LATEST" ]; then
echo "INFO: ACP のログがまだありません。Zed でスレッドを一度開いてから再実行してください"
exit 0
fi
echo "INFO: 最新ログ = $LATEST"
if grep -qE 'Launching browser login flow|Authentication required|-32000' "$LATEST"; then
echo "NEXT: 資格情報がありません。このターミナルで 'agy acp --login' を実行し、Zed のスレッドを開き直してください"
elif grep -qE 'exit status: 255|exited with status' "$LATEST"; then
echo "NEXT: 認証ではなく起動で落ちています。ホスト側のユーザー解決(OS Login など)を確認してください"
else
echo "OK: 直近のログに認証の失敗は見当たりません"
fiなぜこう書いたかを少しだけ補足します。ログの文字列で判定しているのは、パネルの表示が「待っている」以上のことを教えてくれないからです。また、ログの中身をそのまま画面に流さないようにしています——OAuth の URL やコールバックには使い捨てとはいえ認可の情報が含まれるため、点検の出力を誰かに見せる場面でも困らないようにしたかったのです。
それでも直らないときの次の一手
agy acp --login のあとも同じ表示で止まる場合は、次の順に試していただければと思います。
- ACP の「端末でログイン」を選べるか確かめます。公式の認証表には
terminal-loginという方式があり、コードを貼り付ける流れで SSH 越しでも動きます。ただし ACP の端末認証に対応したクライアントにだけ表示されるため、Zed の版によっては出てきません。 - API キーで一時的に入ります。Zed の設定の
envにGEMINI_API_KEYを渡せば、ブラウザを使わずに接続できます。設定ファイルは平文で同期されやすいので、キーを書いたまま共有せず、できればエディタを起動する環境で export しておくと安心です。また、有料プランを Google アカウントで使っている方にとっては、使える枠が変わりうる点も心に留めておいてください。 - ログを公式フォーラムの既存スレッドと突き合わせます。SSH 越しの Zed で OAuth が止まる件は、資格情報を再利用しない不具合として報告されています。自分のログが同じ文言かどうかを見てから書き込むと、話が早く進みます。
フォーラムには、ブラウザ側に出た 127.0.0.1 へのコールバック URL を SSH 先で curl に渡して完了させた、という回避の報告もあります。動く場合もあるのでしょうが、認可コードを手で運ぶ方法は扱いを誤ると危ういため、私はここまで来たら API キーへ切り替える、という線引きにしております。
線引き:サインインはエディタに任せない
最初の十五分、私自身はエディタの設定ばかり見直しておりました。args の綴り、type の値、Zed の再起動。どれも正しく、どれも関係ありませんでした。
いま振り返ると、エディタは「エージェントを起動して会話を中継する係」であって、人の代わりにサインインを済ませる係ではなかったのだと思います。
サインインは画面の前の私が、起動と中継はエディタが。 この分担を意識してからは、リモート先を増やすたびに最初に agy acp --login を打つのが習慣になりました。
同じ考え方は、Remote Control の常駐先を決めるときにも役に立ちます。どの機械に資格情報を置くかの判断は、Remote Control の接続先選びと常駐の止め方にまとめております。
まずは、いまつないでいる SSH 先で agy acp --login を一度だけ実行し、Zed のスレッドを開き直してみてください。それで入れたら、上の点検スクリプトを同じ機械に置いておくと、次に止まった日の自分が少し楽になります。