すぐわかる対処法
- インストール直後に "opencode: command not found"？インストーラーの bin フォルダが PATH に入っていません——シェルのプロファイルで export し（動画では Git Bash 向けに .opencode/bin を追加）、新しいターミナルを開けば直ります。
- インストールスクリプトがエラーを出す？これは Bash スクリプトです——PowerShell から実行すると -fsSL フラグで失敗します。先に VS Code の既定ターミナルプロファイルを Git Bash に切り替えてから、curl -fsSL https://opencode.ai/install | bash を再実行しましょう。
- ターミナルやデスクトップのウィンドウが真っ黒？.local/share/opencode の壊れたデータフォルダを削除し（Windows は AppData\Local\share\opencode）、固まったプロセスを終了して再起動——録画では 1 分以内に TUI が描画し直ります。
- "Free usage exceeded" やプロバイダーエラー？/models でモデルピッカーを開いて別のモデルへ切り替えるか、/connect で再認証を。opencode auth list を実行すれば資格情報が届いているか確認できます。
- モデル一覧に足りないものがある？表示されるのは接続済みプロバイダーだけです。/connect でプロバイダーを追加するか、opencode.json の model・disabled_providers・プロバイダーごとのホワイトリスト/ブラックリストキーで一覧を整理しましょう。
Fix OpenCode Error in Antigravity Terminal (Git Bash + PATH Solution)
チャンネル：teacher account5:52
OpenCode docs — install, config & troubleshooting
ドキュメント：opencode.ai/docs
フレームは 3 本の画面録画から：上の PATH 修正、Windows の黒画面修復（Vũ Văn Hà による xiXPoY2d4iw）、無料枠でのモデル切替（Free Code による DX8MZFuu1BM）。各ステップから該当動画の箇所へ直接飛べます。
動画フレームの著作権は制作者に帰属します。出典とディープリンクを添えて、段階的なドキュメントとして埋め込んでいます。
OpenCode を一歩ずつ直す
インストールと PATH——「コマンドが見つからない」段階
- 1
公式のインストールコマンドを入手する
opencode.ai を開き、インストールボックスからコマンドをコピー——curl -fsSL https://opencode.ai/install | bash——タブを npm・bun・brew に切り替えても OK。OpenCode が「動かない」のが、そもそも完全にインストールできていないせいなら、半端にコピーしたコマンドをデバッグするより、この公式コマンドからやり直すほうが近道です。
curl・npm・bun・brew タブ付きの opencode.ai インストールボックス0:08 から再生 - 2
PowerShell ではなく Bash シェルでインストーラーを実行する
インストールスクリプトは Bash 用に書かれています。PowerShell に貼り付けると、録画に映ったとおり Invoke-WebRequest: A parameter cannot be found that matches parameter name 'fsSL' というエラーに。画面で示された修正は、IDE の settings.json で terminal.integrated.defaultProfile.windows を Git Bash にして、コマンドを Bash シェルに届かせることです。
PowerShell が出した -fsSL エラーと、既定プロファイルの設定を並べた画面1:32 から再生 - 3
PATH を通して "opencode: command not found" を解消する
インストールは終わったのにターミナルがまだ bash: opencode: command not found と言うなら、バイナリのフォルダが PATH に届いていません。録画では Git Bash で export PATH=/c/Users/<you>/.opencode/bin:$PATH を実行して .opencode/bin を追加し、そのまま opencode を再起動——同じ export を ~/.bashrc に書けば永続化します。
command not found、PATH の export、そして成功する再試行4:32 から再生 - 4
Git Bash でインストーラーを再実行して確認する
Git Bash を既定プロファイルにしたら、curl -fsSL https://opencode.ai/install | bash をもう一度最後まで実行します。npm から npm install -g opencode-ai で入れることもでき、Windows なら choco や scoop も使えます。終わったらターミナルを開き直して、更新後の PATH を反映させましょう。
既定プロファイルを Git Bash にしてインストールコマンドを再実行2:30 から再生
黒い画面と起動時のクラッシュ
- 5
黒い画面で起動する症状を見分ける
2 つ目の故障パターン：opencode と打つとウィンドウタイトルは変わるのに、中身は真っ黒——バナーもプロンプトも出ない。録画は Windows 11 で、まさにこの「死んだウィンドウ」を映しています。入力に問題はなく、ディスク上の状態か固まったプロセスが TUI の描画を妨げています。
opencode 起動直後の真っ暗なコマンドプロンプト0:09 から再生 - 6
壊れたデータフォルダを削除する
録画で示された修正：OpenCode を閉じ、タスクマネージャーで固まったインスタンスを終了し、AppData\Local\share\opencode のデータフォルダを削除します（macOS・Linux では ~/.local/share/opencode）。中には auth.json・ログ・プロジェクト状態が入っているので、後で再認証が必要です——動く TUI の前では安いものです。
削除前の AppData\Local\share 下にある opencode データフォルダ0:28 から再生 - 7
再起動して TUI が描画されることを確認する
もう一度 opencode を実行します。録画の次のシーンは健康なターミナル UI——バナー、Ask anything プロンプト、「Run /connect to add an AI provider and start coding」のヒント付き。それでも真っ暗なら opencode --print-logs を付けて起動し、log/ フォルダの最新ファイルで失敗した行を探しましょう。
状態クリーンアップ後に復活した OpenCode TUI1:09 から再生
プロバイダー・モデル・IDE の問題
- 8
切り替える前に無料枠のメッセージを読む
同梱モデルのクォータを使い切ると、セッションは赤い「Free usage exceeded, subscribe to Go [retrying…]」バナーを出して応答しなくなります。クラッシュではありません——録画では別のモデルを選んだ瞬間にセッションが復帰するので、このメッセージは「ステップ 9 へ進め」という合図と読みましょう。
Free usage exceeded バナーと現在のモデル行0:36 から再生 - 9
モデルピッカーを開いて別のモデルを選ぶ
セッション内で /models を実行（シェルからは opencode models）すると、接続済みプロバイダーが提供する全モデルが出ます。録画では OpenCode Zen カタログから別の Free 表記モデルを選択。/connect で接続済みなら、Claude・GPT・Gemini など資格情報のあるモデルはどれでも使えます。
Free 表記モデルとプロバイダーが並ぶ Select model ピッカー0:12 から再生 - 10
選べるなら推論の effort バリアントも選ぶ
一部のモデルでは Default・minimal・medium・high・xhigh を選ぶ 2 つ目の Select variant ダイアログが開きます（録画にも映っています）。低めの effort は速くて安く、難しいリファクタリングには high を。選択は現在のセッションだけに効くので、安心して試せます。
minimal から xhigh までの推論オプションが並ぶ Select variant0:20 から再生 - 11
ステータスバーで切り替えを確認する
プロンプト下のステータスバーにはアクティブなモデルが表示されます——録画では切替後に「Build · Muse Spark 1.2 Free · OpenCode Zen · xhigh」と出て、コンテキストパネルに使用トークンと $0.00 の支出が表示されます。新しいモデルでもエラーが消えない場合は、/connect で再認証し、opencode auth list で確認しましょう。
切り替え後のモデルと effort を確認するステータスバー0:30 から再生 - 12
OpenCode を VS Code に組み込む
「VS Code で動かない」というケース向け：統合ターミナルを開いて opencode を実行すると、OpenCode 拡張が自動インストールされます——録画の Installed 一覧には opencode for VS Code by SST が映っています。以降は Ctrl+Esc で分割ターミナルに OpenCode が開き、だめなら拡張機能マーケットプレイスで「OpenCode」を検索して手動インストールを。
インストール済みの opencode 拡張とインストーラーの実行手順3:02 から再生
それでも直らない？チェックリストをこなす
上の 3 ステージで症状が拾えなかったときのための、残りの故障パターン集——すべて公式ドキュメントに紐付けてあり、症状ではなく原因を直せます。
- 1インストール後も「見つからない」まま——開いたままのターミナルは古い PATH を保持しています。シェルを閉じて開き直し、export の行を ~/.bashrc に書くか（Windows ならシステムプロパティで PATH を設定）、再起動後も生きるようにしましょう。npm ユーザーは、npm のグローバル bin フォルダも PATH に含まれているか確認を。
- 2まったく起動しない——opencode --print-logs で失敗をリアルタイムに確認し、~/.local/share/opencode/log/（Windows は %USERPROFILE%\.local\share\opencode\log）の最新ログを読みます。残るのは直近 10 ログだけで、重要なのは最新の 1 件。バイナリが古そうなら opencode upgrade を試しましょう。
- 3ProviderInitError や "invalid or corrupted configuration"——ドキュメントの処方箋はデータディレクトリの削除（rm -rf ~/.local/share/opencode）と /connect での再認証。ステップ 6 の黒画面修正と同じ治療を、エラーメッセージ側から辿ったものです。
- 4セッション中の AI_APICallError——rm -rf ~/.cache/opencode でプロバイダーパッケージのキャッシュを消して再起動すれば、プロバイダー SDK が再インストールされます。その後 opencode auth list を確認。資格情報の期限切れ・欠落は 2 番目に多い原因です。
- 5Windows のデスクトップアプリが死ぬ——WebView2 ランタイムを更新し、完全終了から再起動、さらにカスタムの server.port / OPENCODE_PORT 上書きを解除しましょう。ドキュメントは Windows で最良の体験のために WSL を推奨していて、ターミナルプロファイル問題の大半もこれで回避できます。
- 6モデルが全部出ない——/models は接続済みプロバイダーだけを列挙します。/connect で追加し、opencode.json でカタログを整理："model": "provider/model-id" を既定に設定、disabled_providers でプロバイダー全体を隠す、各プロバイダーのホワイトリスト/ブラックリストで絞り込む。
リストを順にこなせば、「opencode が動かない」報告の大半は解決します：PATH、次に状態、最後にプロバイダーとモデル。全部だめなら最新のログファイルを添えて OpenCode リポジトリに issue を立てて——メンテナーが求めているのはログで、スクリーンショットではありません。