Antigravity CLIでつまずかないための実践トラブルシューティングガイド

Antigravity CLIを使おうとしたときに、まず不安になるのは「ちゃんとインストールできるのか」「コマンドは正しく動くのか」「エラーが出たときに自分で直せるのか」という部分ではないでしょうか。

特にAntigravity CLIは、AIエージェント、複数モデルの切り替え、API連携、MCPなど、いくつかの仕組みが関係します。

そのため、ただコマンドを1つ覚えるだけでは、トラブル時に原因を切り分けにくいです。

そこでこの記事では、Antigravity CLIでつまずきやすいポイントを、導入前の確認から初期設定、コマンドエラー、API認証、権限、ログ解析、運用監視まで順番に整理しました。

難しい専門用語もできるだけかみ砕きながら、エラーが出たときにどこを見ればいいのか、どの順番で確認すれば復旧しやすいのかを紹介していきます。

Antigravity CLIを安心して使うための確認用ガイドとして、ぜひ参考にしてみてください。

目次−

Antigravity CLIの基本を押さえる

まずは、Antigravity CLIの基本から確認していきましょう。

ここをあいまいにしたまま進めると、後でエラーが出たときに「何が原因なのか」が分かりにくくなります。

Antigravity CLIと`agy`の違い

Antigravity CLIは、複数のLLMや外部ツールを統合して操作するための、コマンドラインベースのAIオーケストレーションツールです。

ここで最初に混乱しやすいのが、正式名称と実際に入力するコマンド名の違いです。

Antigravity CLIは、製品やプロジェクトとしての正式名称です。

一方で、ターミナルやコマンドプロンプトで実際に入力するコマンドはagyです。

たとえば、スマートフォンのアプリ名が「Antigravity」で、ホーム画面に表示される起動アイコンが「agy」だと考えると分かりやすいでしょう。

つまり、実際の操作はすべてagyコマンドを起点にして行います。

ここは最初に押さえておきたいポイントです。

Antigravity CLIでできること

Antigravity CLIは、シンプルなコマンド体系でありながら、AIエージェントの構築、モデルの切り替え、外部API連携、MCPとの統合などを扱える柔軟なツールです。

代表的なコマンドは、次の通りです。

目的	コマンド	内容
初期化	`agy init`	接続設定、APIキー登録、初期ファイル生成
エージェント実行	`agy run [スクリプト名]`	定義したプロンプトやタスクを実行
モデル切り替え	`agy switch [モデル名]`	使用するAIモデルを変更
状態確認	`agy status`	接続状況、APIキー、設定を確認

最初は、すべてのコマンドを覚える必要はありません。

まずは、agy initで初期化して、agy statusで設定状態を確認する流れを覚えておきましょう。

この2つを押さえておくだけでも、後のトラブル対応がかなり楽になります。

Gemini・Claude・MCPの役割

Antigravity CLIでは、複数のAIモデルやプロトコルを組み合わせて使う場面があります。

ここでよく出てくるのが、Gemini、Claude、MCPです。

Geminiは、Googleが開発するマルチモーダルAIモデルです。長いコンテキストを扱うのが得意で、大量のソースコードやドキュメントをまとめて処理したい場合に向いています。

Claudeは、Anthropicが開発するAIモデルです。論理的な推論、自然な文章生成、コード生成などに強みがあります。構造化された指示を与えたときに扱いやすいモデルとして考えられます。

MCPは、Model Context Protocolの略です。AIモデルがローカルファイル、データベース、外部APIなどへ安全にアクセスするための共通規格です。

Antigravity CLIがMCPサーバーと連携すると、AIにファイル操作やコマンド実行を任せるような、自律型エージェントの構成も可能になります。

ただし、ここで大事な注意点があります。

AIが外部ファイルやAPIにアクセスできるということは、便利な反面、権限やセキュリティの確認がかなり重要になるということです。

何でも許可すれば便利になりますが、そのぶん意図しないファイル変更やデータ送信のリスクも高くなります。

APIと利用規約の確認も必要

Antigravity CLIは、内部的にGoogleやAnthropicなどのAIプロバイダが提供するAPIと通信します。

そのため、単に技術的に動かせればOKというわけではありません。

各サービスの利用規約やデータの扱いも確認しておく必要があります。

特に気をつけたいのは、次の3つです。

API経由で送信したデータがどのように扱われるか
短時間に大量アクセスしたときのレートリミット
商用利用時の制限

APIキーを設定すれば、すぐ使えるように見えるかもしれません。

しかし実運用では、「送ってよいデータか」「課金上限は問題ないか」「規約に反していないか」まで確認することが大切です。

ここを飛ばすと、あとから思わぬトラブルにつながることがあります。

導入前に確認したい環境と初期設定

Antigravity CLIを安定して使うためには、いきなりコマンドを打つよりも、先に環境を確認しておくことが大切です。

ここで準備不足があると、インストールや初期化の段階でつまずきやすくなります。

必要な実行環境

Antigravity CLIを動かすには、あらかじめローカルPCに必要な環境を整えておく必要があります。

まず必要になるのがPythonです。

Python 3.10以上が推奨され、パッケージ管理ツールであるpipが使える状態になっている必要があります。

次に必要なのが、ターミナル環境です。

WindowsであればPowerShellやWindows Terminal、Macであればターミナル.app、Linuxであれば各ディストリビューションのターミナルを使います。

また、設定ファイルの編集やログ確認には、VS CodeやCursorのようなIDE・エディタがあると便利です。

特にJSONやYAMLの構文エラーを検出できる拡張機能を入れておくと、カンマの付け忘れやクォート漏れをすぐに見つけやすくなります。

さらに、APIキーの発行やアカウント管理にはブラウザも必要です。

Google AI StudioやAnthropic Consoleなどの管理画面で、APIキーの作成、支払い設定、利用規約の確認を行います。

インストール手順

基本的なインストールは、pipを使って実行します。

pip install antigravity-cli

MacやLinuxで権限エラーが出る場合は、ユーザー領域へインストールする方法もあります。

pip install --user antigravity-cli

インストール後は、まずターミナルを再起動するのがおすすめです。

特にWindowsでは、PATHの反映にターミナルの再起動が必要になることがあります。

「インストールは成功したのにコマンドが動かない」という場合も、ターミナルを開き直すだけで解決することがあります。

Windowsで`agy`が認識されない場合

Windowsでインストール後にagyコマンドが認識されない場合、PythonのScriptsフォルダにPATHが通っていない可能性があります。

たとえば、次のような場所です。

C:\Users\<ユーザー名>\AppData\Local\Programs\Python\Python31x\Scripts

このフォルダがユーザー環境変数のPathに含まれていないと、pip installが成功していてもagyを実行できません。

確認する場合は、まず次のコマンドでインストール先を見ます。

pip show antigravity-cli

その後、Windowsの「環境変数を編集」からPathへScriptsフォルダを追加します。

追加したら、PowerShellを完全に閉じてから開き直しましょう。

PATHを変更しただけでは、すでに開いているターミナルには反映されないことがあります。

ここは地味ですが、かなりつまずきやすいポイントです。

Mac・Linuxで注意したいこと

MacやLinuxでは、インストール後にシェル設定の再読み込みが必要になる場合があります。

source ~/.zshrc

または、ターミナルを一度閉じて再起動します。

実行権限でエラーが出る場合は、対象ファイルに実行権限を付与します。

chmod +x ./script.py

ファイルやフォルダの所有者が別ユーザーになっている場合は、所有権の確認も必要です。

特に、過去にsudoを使ってインストールやファイル作成をしている場合、現在のユーザーでは操作できない状態になっていることがあります。

APIキーと初期化

インストールが完了したら、次に初期化を行います。

agy init

このコマンドを実行すると、対話形式の初期設定ウィザードが始まります。

利用規約やデータアクセスに関する確認が表示されたら、内容を確認します。

承認が必要な場面では、yを入力してEnterを押します。

Geminiを使う場合は、Google AI Studioで取得したGEMINI_API_KEYを設定します。

Claudeを使う場合は、Anthropic Consoleで取得したANTHROPIC_API_KEYを設定します。

APIキーを貼り付けるときは、前後に余計なスペースや改行が入らないように注意してください。

認証エラーの原因として、コピー時の1文字欠落や不要な空白はかなり多いです。

見た目では分かりにくいので、うまくいかない場合は新しいキーを発行し直す方が早いこともあります。

設定ファイルの確認

agy initが正常に終わると、ホームディレクトリやカレントフォルダに設定ファイルが生成されます。

たとえば、次のような構造です。

{
  "default_model": "claude-3-5-sonnet",
  "api_keys": {
    "gemini": "AIzaSy...",
    "claude": "sk-ant-..."
  },
  "mcp_servers": {},
  "timeout": 30,
  "log_level": "INFO"
}

初期設定後は、必ず次のコマンドを実行しましょう。

agy status

ここでAPIキー、接続状態、設定ファイルの読み込みが正常かを確認します。

最初の段階でagy statusを確認しておくと、後からエラーが起きたときに原因を切り分けやすくなります。

具体的には、次のような判断ができます。

そもそも初期設定が失敗しているのか
APIキーの読み込みだけが失敗しているのか
実行時だけ問題が起きているのか

トラブル対応では、最初の状態確認がかなり大事です。

コマンド実行時によく起きるトラブルと対処法

ここからは、実際にAntigravity CLIを使うときによく起きるトラブルと、その対処法を紹介します。

エラーが出ると焦ってしまいますが、見るべき場所はだいたい決まっています。

順番に確認していきましょう。

`Command not found: agy`が出る場合

Command not found: agyや、Windowsで「agyは認識されません」と表示される場合は、主に次のどちらかです。

インストールが完了していないか、PATHが通っていません。

まずは、ターミナルを完全に再起動します。

それでも解決しない場合は、Pythonモジュールとして直接起動できるか試します。

python -m agy

これで動く場合、パッケージ自体は入っています。

ただし、agyコマンドへのPATHが通っていない可能性が高いです。

WindowsであればPythonのScriptsフォルダ、MacやLinuxであれば~/.local/binなどがPATHに含まれているか確認しましょう。

引数の指定ミス

コマンドの引数が足りない、または形式が違う場合もよくあります。

たとえば、次のような実行です。

agy run claude

この形式では、claudeをスクリプト名として解釈してしまうか、必要なオプションが足りない可能性があります。

モデルを指定してスクリプトを実行する場合は、次のようにオプションを明確にします。

agy run --model claude script.py

コマンドがうまく動かないときは、まずヘルプを確認しましょう。

agy --help
agy run --help

ヘルプを読むことで、どの引数が必須で、どのオプションが使えるかを確認できます。

分からないまま何度も実行するより、先にヘルプを見る方が早いです。

Permission Deniedが出る場合

Permission Deniedやos error 13が出る場合は、ローカルファイルの権限か、APIアクセス権限のどちらかに問題があります。

ローカルファイルの権限であれば、対象スクリプトに実行権限を付与します。

chmod +x ./run_agent.sh

設定フォルダの所有権に問題がある場合は、現在のユーザーに所有権を戻します。

chown -R $(whoami) ~/.config/antigravity-cli/

Windowsで権限エラーが出る場合は、PowerShellを「管理者として実行」することで解決することがあります。

ただし、毎回管理者権限で実行するのはおすすめしません。

最終的には、フォルダ権限やインストール先を見直す方が安全です。

APIアクセス拒否の確認

API側の認証権限が原因の場合は、APIキーの状態を確認します。

確認したいのは、次の点です。

APIキーが有効か
支払い設定が完了しているか
対象モデルへのアクセス権があるか
設定ファイルへ正しく反映されているか

また、設定ファイルに貼り付けたAPIキーの前後に空白が入っていないか、改行が混ざっていないかも確認しましょう。

APIキーの入力ミスは、見た目では分かりにくいです。

怪しい場合は、古いキーを削除して新しいキーを発行し、設定し直す方が早いです。

タイムアウトや接続失敗の切り分け

TimeoutErrorが出る、あるいはコマンドが止まったまま戻ってこない場合は、順番に切り分けます。

まず、ローカルのインターネット接続が正常か確認します。

ブラウザで外部サイトが開けるか、別のAPI通信ができるかを見てみましょう。

次に、AIプロバイダ側のサーバー状況を確認します。

クラウド側で障害や遅延が起きている場合、ローカル環境をいくら直しても改善しません。

サーバー側が正常であれば、次に確認したいのは通信環境です。

プロキシ
VPN
セキュリティソフト
ファイアウォール
社内ネットワークの制限

社内ネットワークでは、外部APIへの通信が制限されていることがあります。

プロキシが必要な環境では、次のような環境変数を設定する必要があります。

HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080

通信系のトラブルは、Antigravity CLIそのものではなく、ネットワーク環境が原因になっていることも多いです。

ログの読み方

エラーが出たときは、ターミナルの最後の1行だけを見るのは危険です。

大切なのは、最初にErrorやExceptionが出た行を探すことです。

標準出力は、正常に処理された結果が出る場所です。

標準エラー出力は、エラーメッセージやスタックトレースが出る場所です。

また、.agy/artifacts/のようなフォルダに、一時ファイルや中間成果物が残る場合があります。

そこにログやトレースが保存されていれば、AIとの通信内容や途中で生成されたデータを確認できます。

詳細ログを取りたい場合は、--verboseを付けて実行します。

agy run script.py --verbose

または、環境変数でログレベルを上げます。

AGY_LOG_LEVEL=DEBUG agy run script.py

通常ログだけでは分からない場合でも、詳細ログを見ることで、APIリクエスト、レスポンス、設定ファイルの読み込み状況、タイムアウト箇所などを追いやすくなります。

API・モデル連携・MCPまわりの診断方法

Antigravity CLIでは、APIやモデル連携の部分でエラーが起きることもあります。

ここでは、よく出るエラーコードや、Gemini・Claude・MCPまわりの確認ポイントを紹介します。

401 Unauthorized

401 Unauthorizedは、認証に失敗している状態です。

主な原因は、次の通りです。

APIキーの入力ミス
APIキーの期限切れ
設定ファイルへの反映漏れ
対象サービス側でキーが無効化されている

この場合は、管理画面でAPIキーが有効か確認します。

必要であれば、古いキーを削除して新しいキーを発行しましょう。

その後、agy initを再実行して、設定を更新します。

最後に、次のコマンドで状態を確認します。

agy status

ここで接続が成功すれば、認証まわりの問題は解消できています。

429 Too Many Requests

429 Too Many Requestsは、短時間にリクエストを送りすぎたときに出るエラーです。

無料枠の上限に達した場合や、1分あたりのリクエスト数を超えた場合にも発生します。

対策としては、次のような方法があります。

スクリプト内に待機時間を入れる
リクエストをまとめる
並列実行数を減らす
有料プランや上位プランを検討する

自動化スクリプトでは、指数バックオフを入れておくと安定しやすくなります。

1回目の失敗 → 2秒待つ
2回目の失敗 → 4秒待つ
3回目の失敗 → 8秒待つ

このように、失敗するたびに待機時間を伸ばして再試行すると、一時的な混雑に強くなります。

エラーが出たからといって、すぐ連打するのは逆効果です。

400 Bad Requestやトークン上限

400 Bad Requestやトークン上限のエラーは、送信したプロンプトやコードの量が多すぎるときに発生します。

特に、プロジェクト全体のソースコードを一度に読ませようとすると、モデルのコンテキスト上限を超えることがあります。

この場合は、ファイル単位、関数単位、目的単位に分けて実行しましょう。

たとえば、次のような指示は負荷が高くなります。

このプロジェクト全体を全部読み、問題点を修正して保存してください。

より安全なのは、次のような分割です。

まずmain.pyの関数Aだけを確認し、改善点を箇条書きで出してください。ファイルの書き換えはまだ行わないでください。

AIエージェントに大きな作業をさせるときは、一度にすべて任せるより、確認ステップを挟みながら進める方が安定します。

GeminiとClaudeで挙動が違う理由

同じプロンプトでも、GeminiとClaudeで出力が変わることがあります。

これは、モデルごとの得意分野や設計思想が違うためです。

コード生成や厳密な出力を求める場合は、Temperatureを低めに設定します。

たとえば、0.0から0.2程度にすると、出力の揺れを抑えやすくなります。

一方で、アイデア出しや文章表現のバリエーションが欲しい場合は、少し高めに設定することもあります。

また、ClaudeはXMLタグのような構造化された指示を扱いやすい傾向があります。

<instruction>
JSON形式だけで出力してください。
余計な説明文は出力しないでください。
</instruction>

Geminiでは、段階的で具体的なプレーンテキストの指示が合う場面があります。

モデルを切り替えるときは、単にagy switchで変更するだけでは不十分です。

モデルごとに、プロンプトの書き方も見直すことが重要です。

クラウド環境で動かない場合

ローカルPCでは動くのに、AWS、GCP、Heroku、CI環境などにデプロイすると動かない場合があります。

よくある原因は、環境変数の未設定です。

ローカルの設定ファイルは、セキュリティ上.gitignoreに入れてリポジトリへ含めないことが多いです。

そのため、クラウド環境では別途APIキーを登録する必要があります。

たとえば、次のような環境変数をクラウド側の管理画面に設定します。

GEMINI_API_KEY
ANTHROPIC_API_KEY

また、クラウド環境によっては、外部APIへのアウトバウンド通信が制限されていることがあります。

api.anthropic.comやgenerativelanguage.googleapis.comなどへの通信が許可されているか確認しましょう。

MCP連携で確認したいこと

MCPを使う場合は、AIがどのファイルや外部サービスにアクセスできるのかを明確にしておく必要があります。

アクセス権限が広すぎると、意図しないファイルの読み書きや、不要なAPI呼び出しが起きる可能性があります。

MCPサーバーを設定するときは、次の考え方が大切です。

最小限のフォルダだけ許可する
最小限の権限だけ与える
必要なAPIだけ連携する

また、ファイルロックや長時間処理が発生すると、エージェントが応答しないように見えることがあります。

その場合は、Ctrl + Cで一度停止し、ログやアーティファクトを確認しましょう。

MCPは便利ですが、便利さと安全性はセットで考える必要があります。

開発・自動化・運用で困らないための実践ポイント

ここからは、Antigravity CLIを開発や自動化、運用で使うときに困らないための実践ポイントを紹介します。

手動では動くのに、自動化すると動かない。

ローカルでは問題ないのに、本番では失敗する。

このあたりはよく起きます。

自動化で多いカレントディレクトリ問題

手動でコマンドを実行すると動くのに、cron、タスクスケジューラ、シェルスクリプト、Pythonスクリプトから実行すると動かない場合があります。

この原因として多いのが、カレントディレクトリの違いです。

手動実行ではプロジェクトフォルダにいるつもりでも、自動実行では別のディレクトリから実行されていることがあります。

その結果、設定ファイルが見つからない、相対パスのファイルが読めない、といったエラーになります。

対策としては、スクリプト内で明示的に作業ディレクトリへ移動します。

cd /Users/username/my-workspace/project_A
agy run agent.py

または、ファイルパスを相対パスではなく絶対パスで指定します。

agy run /Users/username/my-workspace/project_A/agent.py

自動化では、「今どこのフォルダで実行されているか」を必ず意識しましょう。

指示が効かないときのプロンプト改善

AIエージェントが意図通りに動かないときは、プロンプトが曖昧なことがあります。

たとえば、「いい感じに直して」では、どこまで変更してよいのか分かりません。

効果的なのは、次の4つを明確にすることです。

役割
対象範囲
出力形式
禁止事項

たとえば、次のように書きます。

あなたはPythonコードレビュー担当です。
対象はmain.pyの関数Aだけです。
構文エラー、例外処理、可読性の観点で確認してください。
出力は「問題点」「修正案」「修正後コード」の3項目に分けてください。
ファイルの直接変更は行わないでください。

このように指示すると、エージェントの行動範囲が明確になります。

その結果、不要なファイル変更や見当違いの提案を減らせます。

AIエージェントには、自由すぎる指示よりも、範囲を絞った指示の方が効きやすいです。

IDEでのデバッグ

VS CodeやCursorを使う場合は、設定ファイルの構文エラーを検知できる拡張機能を入れておくと便利です。

JSONファイルでは、カンマの付け忘れや閉じ括弧の不足が原因で設定が読み込めないことがあります。

また、.envでAPIキーを管理している場合は、実行時に環境変数が正しく読み込まれているか確認します。

import os

print(os.environ.get("GEMINI_API_KEY"))

ただし、ここは注意が必要です。

実際の運用ログにAPIキーそのものを出力するのは危険です。

確認が終わったら、必ず出力コードを削除しましょう。

確認用のコードを残したままにすると、ログ経由でAPIキーが漏れる可能性があります。

複数プロジェクトの設定管理

複数のプロジェクトでAntigravity CLIを使う場合、PC全体で1つの設定ファイルだけを使うと、APIキーやモデル設定が混ざる可能性があります。

プロジェクトごとに設定を分けると安全です。

my-workspace/
├── project_A/
│   ├── .agyconfig
│   └── agent.py
└── project_B/
    ├── .agyconfig
    └── automation.sh

カレントディレクトリに.agyconfigがある場合、そのプロジェクト専用の設定として読み込める構成にしておくと便利です。

クライアントごとのAPIキーやモデル設定も分離できます。

また、セキュリティ事故を防ぐためにも、設定ファイルをGitに含めないようにします。

.agyconfig
.env

これらは.gitignoreに入れておくのが基本です。

設定ファイルにはAPIキーや環境情報が含まれることがあるため、公開リポジトリへ入れるのは避けましょう。

CI/CDでの注意点

GitHub ActionsやGitLab CI/CDにAntigravity CLIを組み込む場合は、依存関係の固定が重要です。

毎回最新版をインストールすると、ある日突然、仕様変更で動かなくなる可能性があります。

antigravity-cli==1.X.X

このようにrequirements.txtでバージョンを固定しておくと、再現性が高まります。

また、CIのジョブ終了後にログや生成ファイルが消えてしまうことがあります。

テスト結果や生成コードを後から確認したい場合は、アーティファクトとして保存する設定を入れます。

artifacts:
  paths:
    - .agy/artifacts/
    - reports/

これにより、失敗時の原因調査がしやすくなります。

CI/CDでは、失敗した後に原因を追える状態を作っておくことが大切です。

APIキーの安全な管理

APIキーをソースコードへ直接書くのは避けるべきです。

GitHub Actionsでは、Settings -> Secrets and variables -> ActionsにAPIキーを登録し、ワークフローから呼び出します。

env:
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

また、自動化ジョブに与える権限は最小限にします。

読み取りだけでよい処理に、書き込み権限を与える必要はありません。

AIエージェントは便利ですが、権限を広く与えすぎると、予期しないファイル変更やデータ送信が起きるリスクがあります。

APIキーは、便利さよりも安全管理を優先しましょう。

監視すべきポイント

本番運用でAntigravity CLIを使う場合は、ログ監視やメトリクスの確認が欠かせません。

特に見るべきなのは、次の3つです。

エラーレート
レスポンスタイム
トークン消費量

エラーレートが急に増えた場合は、APIキー、レートリミット、モデル側の障害、プロンプト変更の影響などが考えられます。

レスポンスタイムが急に遅くなった場合は、AIプロバイダ側の混雑、プロンプトの肥大化、MCP連携の遅延が疑われます。

トークン消費量が想定より多い場合は、プロンプトが長すぎる、不要なログやソースコードを毎回送っている、同じ処理を繰り返している可能性があります。

本番運用では、動いているかどうかだけでなく、どれくらい安定して動いているかを見ることが大切です。

ロールバックの準備

プロンプトやモデル設定を変更した直後に、エージェントが予期しない動きをすることがあります。

そのため、変更前の設定ファイルやGitのコミットハッシュを残しておくことが重要です。

問題が起きたら、すぐに前の状態へ戻せるようにしておきましょう。

また、いきなり全体に反映するのではなく、一部のフォルダや一部の処理だけで試すカナリアリリースも有効です。

まずは小さく試し、問題がないことを確認してから全体へ広げる方が安全です。

AIエージェントの運用では、一気に変えないことも大事なリスク対策です。

最小再現環境を作る

複雑なエラーが起きたときは、最小再現環境を作るのが効果的です。

長いプロンプトから不要な部分を削り、3行程度のシンプルな指示にします。

複雑なコードから、エラーを起こしている関数だけを取り出します。

新しい空のフォルダを作り、最小限の設定ファイルだけで実行します。

手順としては、次の通りです。

1. 長いプロンプトを短くする
2. 問題の関数だけを取り出す
3. 空のフォルダで再実行する
4. 同じエラーが再現するか確認する

同じエラーが再現するなら、ツールやコードの問題である可能性が高いです。

再現しないなら、元の環境、設定ファイル、依存関係、ネットワークなどに原因がある可能性があります。

エラー調査では、いきなり全部を直そうとしないことが大切です。

問題を小さくしてから確認する方が、原因にたどり着きやすくなります。

実例：Windowsで`agy init`が起動しない

WindowsのPowerShellで、次のようなエラーが出ることがあります。

agy : 用語 'agy' は、コマンドレット、関数、スクリプト ファイル、
または操作可能なプログラムの名前として認識されません。

この場合、pip install antigravity-cliは成功していても、PythonのScriptsフォルダがPATHに入っていない可能性があります。

復旧手順は次の通りです。

pip show antigravity-cli

まず、インストール先を確認します。

その後、PythonのScriptsフォルダを環境変数Pathに追加します。

Pathへ追加したら、PowerShellを完全に閉じ、新しいウィンドウで起動します。

再度、次を実行します。

agy init

初期化画面が表示されれば復旧完了です。

実例：API認証に失敗する

agy runで、次のようなエラーが出る場合があります。

AuthenticationError: 401 Unauthorized

この場合は、APIキーが間違っている、期限切れ、無効化されている、または設定ファイルに正しく反映されていない可能性があります。

復旧の流れは次の通りです。

1. 管理画面で古いAPIキーを削除する
2. 新しいAPIキーを発行する
3. agy initを再実行する
4. 利用規約を確認して承認する
5. 新しいAPIキーを貼り付ける
6. agy statusで接続を確認する

ここまで行ってagy statusが成功すれば、認証エラーは解消できています。

API認証のエラーでは、悩みすぎるよりも、新しいキーを発行して設定し直す方が早い場合があります。

実例：エージェントが応答しない

AIエージェントに大きな作業を一度に任せると、応答が返ってこないことがあります。

たとえば、次のような指示です。

このプロジェクト全体のコードを綺麗にしてファイルに保存して。

この指示では、対象範囲が広すぎます。

エージェントが内部で何度も判断を繰り返し、処理が止まっているように見える場合があります。

この場合は、Ctrl + Cで一度停止します。

その後、ログを確認します。

.agy/artifacts/latest_trace.log

同じような思考や処理を繰り返している場合は、指示を小さく分けましょう。

まずmain.pyの関数Aだけを確認してください。
改善点だけを出力してください。
ファイルの書き込みは行わないでください。

このように、確認、提案、修正、保存を段階に分けると、エージェントの処理が安定しやすくなります。

AIエージェントには、一気に任せるより、段階的に任せる方が安全です。

まとめ

Antigravity CLIを安定して使うためには、agyコマンドの基本、PythonやPATHなどの実行環境、APIキーの設定、モデルごとの違い、ログの読み方を順番に押さえることが大切です。

エラーが起きたときは、いきなり複雑な原因を疑う必要はありません。

まずは、次の順番で確認してみてください。

1. インストール
2. PATH
3. 設定ファイル
4. APIキー
5. ネットワーク
6. 権限
7. レートリミット
8. ログ

この順番で見ていくと、原因を切り分けやすくなります。

また、AIエージェントには一度に大きな作業を任せるより、対象範囲を絞って段階的に指示する方が安定します。

CI/CDや本番運用では、APIキーを安全に管理し、ログやアーティファクトを残し、ロールバックできる状態を作っておくことも重要です。

Antigravity CLIは便利な反面、外部APIやファイル操作と密接に関わります。

だからこそ、最小権限、明確なプロンプト、丁寧なログ確認を習慣にしておきましょう。

この3つを意識するだけでも、トラブルにかなり強い運用ができます。

よくある質問

Q1. `agy`コマンドが認識されないときは何を確認すればいいですか？

まずターミナルを再起動し、それでも動かない場合はPATHを確認しましょう。

Windowsでは、PythonのScriptsフォルダが環境変数Pathに入っているかが重要です。

pip show antigravity-cliでインストール先を確認し、必要に応じてPathへ追加します。

その後、PowerShellやターミナルを完全に閉じてから開き直してください。

Q2. `401 Unauthorized`が出た場合はどうすればいいですか？

APIキーの入力ミス、期限切れ、無効化、設定ファイルへの反映漏れが考えられます。

まず管理画面でAPIキーの状態を確認しましょう。

怪しい場合は、新しいキーを発行してagy initを再実行します。

その後、agy statusで接続確認をしてください。

Q3. エージェントの応答が遅い、または止まったように見える原因は何ですか？

プロンプトが長すぎる、対象範囲が広すぎる、MCP連携でファイルロックが起きている、API側が混雑している可能性があります。

一度Ctrl + Cで停止し、ログを確認しましょう。

そのうえで、作業を小さなステップに分けて再実行すると改善しやすいです。

Q4. GeminiとClaudeはどう使い分ければいいですか？

大量の情報や長いドキュメントを扱う場合はGemini、論理的な文章生成やコードレビュー、構造化された指示を使いたい場合はClaudeが向いている場面があります。

ただし、同じプロンプトでも出力は変わります。

モデルを切り替えるときは、agy switchだけでなく、プロンプトの書き方も調整しましょう。

Q5. 本番運用で特に注意すべきことは何ですか？

本番運用で特に注意したいのは、APIキーの管理と権限設定です。

APIキーをソースコードに直接書かないこと、権限を最小限にすること、ログとアーティファクトを保存すること、レートリミットとトークン消費量を監視することが重要です。

また、設定変更やプロンプト修正の前には、すぐ戻せるようにロールバック手順を用意しておくと安心です。