トラブルシューティング

よくある問題とその解決方法。

OpenCode の問題をデバッグするには、まず、ディスク上に保存されているログとローカルデータを確認します。

ログ

ログファイルは次の場所に書き込まれます。

macOS/Linux: ~/.local/share/opencode/log/
Windows: WIN+R を押して %USERPROFILE%\.local\share\opencode\log を貼り付けます

ログファイルにはタイムスタンプ付きの名前が付けられ (例: 2025-01-09T123456.log)、最新の 10 個のログファイルが保存されます。

--log-level コマンドラインオプションを使用してログレベルを設定すると、より詳細なデバッグ情報を取得できます。たとえば、opencode --log-level DEBUG。

ストレージ

opencode は、セッションデータとその他のアプリケーションデータをディスク上の次の場所に保存します。

macOS/Linux: ~/.local/share/opencode/
Windows: WIN+R を押して %USERPROFILE%\.local\share\opencode を貼り付けます

このディレクトリには次のものが含まれます。

auth.json - API キー、OAuth トークンなどの認証データ
log/ - アプリケーションログ
project/ - セッションデータやメッセージデータなどのプロジェクト固有のデータ
- プロジェクトが Git リポジトリ内にある場合は、./<project-slug>/storage/ に保存されます
- Git リポジトリではない場合は、./global/storage/ に保存されます

デスクトップアプリ

OpenCode Desktop は、ローカル OpenCode サーバー (opencode-cli サイドカー) をバックグラウンドで実行します。ほとんどの問題は、誤動作するプラグイン、破損したキャッシュ、または不正なサーバー設定によって発生します。

クイックチェック

アプリを完全に終了して再起動します。
アプリにエラー画面が表示された場合は、再起動 をクリックしてエラーの詳細をコピーします。
macOS のみ: OpenCode メニュー -> Webview を再ロード (UI が空白またはフリーズしている場合に役立ちます)。

プラグインを無効にする

デスクトップアプリが起動時にクラッシュしたり、ハングしたり、異常な動作をしたりする場合は、まずプラグインを無効にしてください。

グローバル設定を確認してください

グローバル設定ファイルを開き、plugin キーを探します。

macOS/Linux: ~/.config/opencode/opencode.jsonc (または ~/.config/opencode/opencode.json)
macOS/Linux (古いインストール): ~/.local/share/opencode/opencode.jsonc
Windows: WIN+R を押して %USERPROFILE%\.config\opencode\opencode.jsonc を貼り付けます

プラグインを構成している場合は、キーを削除するか空の配列に設定して、プラグインを一時的に無効にします。

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [],
}

プラグインのディレクトリを確認する

OpenCode はディスクからローカルプラグインをロードすることもできます。これらを一時的に邪魔にならない場所に移動し (またはフォルダーの名前を変更し)、デスクトップアプリを再起動します。

グローバルプラグイン
- macOS/Linux: ~/.config/opencode/plugins/
- Windows: WIN+R を押して %USERPROFILE%\.config\opencode\plugins を貼り付けます
プロジェクトプラグイン (プロジェクトごとの構成を使用する場合のみ)
- <your-project>/.opencode/plugins/

アプリが再び動作し始めた場合は、プラグインを 1 つずつ再度有効にして、問題の原因となっているプラグインを特定します。

キャッシュをクリアする

プラグインを無効にしても解決しない場合 (またはプラグインのインストールが停止した場合)、OpenCode がキャッシュを再構築できるようにキャッシュをクリアします。

OpenCode Desktop を完全に終了します。
キャッシュディレクトリを削除します。

macOS: Finder -> Cmd+Shift+G -> ~/.cache/opencode を貼り付け
Linux: ~/.cache/opencode を削除します (または rm -rf ~/.cache/opencode を実行します)。
Windows: WIN+R を押して %USERPROFILE%\.cache\opencode を貼り付けます

OpenCode デスクトップを再起動します。

サーバー接続の問題を修正する

OpenCode Desktop は、独自のローカルサーバー (デフォルト) を起動することも、構成したサーバー URL に接続することもできます。

「接続に失敗しました」 ダイアログが表示された場合 (またはアプリがスプラッシュ画面を通過できない場合)、カスタムサーバー URL を確認してください。

デスクトップのデフォルトのサーバー URL をクリアします

ホーム画面でサーバー名 (ステータスドット付き) をクリックしてサーバーピッカーを開きます。 [デフォルトサーバー] セクションで、[クリア] をクリックします。

設定から `server.port` / `server.hostname` を削除します

opencode.json(c) に server セクションが含まれている場合は、それを一時的に削除し、デスクトップアプリを再起動します。

環境変数を確認する

環境に OPENCODE_PORT が設定されている場合、デスクトップアプリはローカルサーバーにそのポートを使用しようとします。

OPENCODE_PORT の設定を解除して (または空きポートを選択して)、再起動します。

Linux: Wayland / X11 の問題

Linux では、一部の Wayland セットアップにより、空白のウィンドウやコンポジターエラーが発生する可能性があります。

Wayland を使用していて、アプリが空白またはクラッシュしている場合は、OC_ALLOW_WAYLAND=1 で起動してみてください。
これにより状況が悪化する場合は、それを削除し、代わりに X11 セッションで起動してみてください。

Windows: WebView2 ランタイム

Windows では、OpenCode Desktop には Microsoft Edge WebView2 ランタイムが必要です。アプリが空白のウィンドウで開くか、起動しない場合は、WebView2 をインストールまたは更新して、もう一度試してください。

Windows: 一般的なパフォーマンスの問題

Windows でパフォーマンスの低下、ファイルアクセスの問題、またはterminal の問題が発生している場合は、WSL (Windows Subsystem for Linux) を使用してみてください。 WSL は、OpenCode の機能とよりシームレスに連携する Linux 環境を提供します。

通知が表示されない

OpenCode Desktop では、次の場合にのみシステム通知が表示されます。

OS 設定で OpenCode の通知が有効になっており、
アプリウィンドウにフォーカスがありません。

デスクトップアプリのストレージをリセットする (最後の手段)

アプリが起動せず、UI 内から設定をクリアできない場合は、デスクトップアプリの保存された状態をリセットします。

OpenCode デスクトップを終了します。
これらのファイルを見つけて削除します (これらのファイルは OpenCode デスクトップアプリのデータディレクトリにあります)。

opencode.settings.dat (デスクトップのデフォルトサーバー URL)
opencode.global.dat および opencode.workspace.*.dat (最近のサーバー/プロジェクトなどの UI 状態)

ディレクトリをすばやく見つけるには:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (その後、上記のファイル名を検索します)
Linux: 上記のファイル名を ~/.local/share で検索します。
Windows: WIN+R -> %APPDATA% を押します (その後、上記のファイル名を検索します)。

助けを求める

OpenCode で問題が発生している場合:

GitHub で問題を報告してください

バグを報告したり、機能をリクエストしたりする最良の方法は、GitHub リポジトリを使用することです。

github.com/anomalyco/opencode/issues

新しい問題を作成する前に、既存の問題を検索して、問題がすでに報告されているかどうかを確認してください。

Discord に参加してください

リアルタイムのヘルプやコミュニティのディスカッションについては、Discord サーバーに参加してください。

opencode.ai/discord

よくある問題

ここでは、いくつかの一般的な問題とその解決方法を示します。

OpenCodeが起動しない

ログでエラーメッセージを確認する
--print-logs で実行して、terminal に出力を確認してください。
opencode upgrade を含む最新バージョンを使用していることを確認してください

認証の問題

TUI で /connect コマンドを使用して再認証を試みます
API キーが有効であることを確認してください
ネットワークでプロバイダーの API への接続が許可されていることを確認してください

モデルがありません

プロバイダーで認証されていることを確認してください
構成内のモデル名が正しいことを確認してください
一部のモデルでは、特定のアクセスまたはサブスクリプションが必要な場合があります

ProviderModelNotFoundError が表示された場合は、間違いがある可能性が高くなります。どこかのモデルを参照しています。モデルは次のように参照する必要があります: <providerId>/<modelId>

例:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

どのモデルにアクセスできるかを確認するには、opencode models を実行します。

ProviderInitError

ProviderInitError が発生した場合は、構成が無効または破損している可能性があります。

これを解決するには:

まず、プロバイダーガイドに従って、プロバイダーが正しく設定されていることを確認します。
問題が解決しない場合は、保存されている構成をクリアしてみてください。
Terminal window
```
rm -rf ~/.local/share/opencode
```

Windows では、WIN+R を押して、%USERPROFILE%\.local\share\opencode を削除します。

TUI の /connect コマンドを使用して、プロバイダーで再認証します。

AI_APICallError とプロバイダーパッケージの問題

API 呼び出しエラーが発生した場合は、プロバイダーパッケージが古いことが原因である可能性があります。 opencode は、必要に応じてプロバイダーパッケージ (OpenAI、Anthropic、Google など) を動的にインストールし、ローカルにキャッシュします。

プロバイダーパッケージの問題を解決するには:

プロバイダーパッケージのキャッシュをクリアします。
Terminal window
```
rm -rf ~/.cache/opencode
```

Windows では、WIN+R を押して、%USERPROFILE%\.cache\opencode を削除します。

opencodeを再起動して最新のプロバイダーパッケージを再インストールします

これにより、opencodeはプロバイダーパッケージの最新バージョンを強制的にダウンロードすることになり、多くの場合、モデルパラメーターや API の変更に関する互換性の問題が解決されます。

Linux ではコピー/ペーストが機能しない

Linux ユーザーがコピー/ペースト機能を動作させるには、次のクリップボードユーティリティのいずれかがインストールされている必要があります。

X11 システムの場合:

apt install -y xclip
# or
apt install -y xsel

Wayland システムの場合:

apt install -y wl-clipboard

ヘッドレス環境の場合:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode は、Wayland を使用していて wl-clipboard を優先しているかどうかを検出します。そうでない場合は、xclip および xsel の順序でクリップボードツールを検索しようとします。