トラブルシューティング

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

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 Desktop を再起動します。

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

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 Runtime が必要です。アプリが空白のウィンドウで開くか起動しない場合、WebView2 をインストール/更新して再試行してください。

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

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

通知が表示されない

OpenCode Desktop は以下の場合にのみシステム通知を表示します：

OS 設定で OpenCode の通知が有効になっている、かつ
アプリウィンドウがフォーカスされていない。

デスクトップアプリのストレージをリセット（最終手段）

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

OpenCode Desktop を終了します。
これらのファイルを見つけて削除します（OpenCode Desktop アプリデータディレクトリにあります）：

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 (opens in a new tab)

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

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

opencode.ai/discord (opens in a new tab)

よくある問題

以下はよくある問題とその解決方法です。

OpenCode が起動しない

ログでエラーメッセージを確認
--print-logs を付けて実行し、ターミナルで出力を確認
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 が発生した場合、無効または破損した設定がある可能性があります。

これを解決するには：

まず、プロバイダーガイドに従ってプロバイダーが正しく設定されていることを確認
問題が解決しない場合、保存された設定をクリアしてみてください：
```
rm -rf ~/.local/share/opencode
```
Windows では、WIN+R を押して削除：%USERPROFILE%\.local\share\opencode
TUI で /connect コマンドを使用してプロバイダーと再認証します。

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

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

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

プロバイダーパッケージのキャッシュをクリア：
```
rm -rf ~/.cache/opencode
```
Windows では、WIN+R を押して削除：%USERPROFILE%\.cache\opencode
opencode を再起動して最新のプロバイダーパッケージを再インストール

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

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

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

X11 システムの場合：

apt install -y xclip
# または
apt install -y xsel

Wayland システムの場合：

apt install -y wl-clipboard

ヘッドレス環境の場合：

apt install -y xvfb
# そして実行：
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

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

エンタープライズ Windows (WSL)