コンテンツにスキップ
ショーケース エコシステム ソースコード ドキュメント

トラブルシューティング

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 サイドカー) をバックグラウンドで実行します。ほとんどの問題は、動作不良のプラグイン、破損したキャッシュ、不正なサーバー設定が原因です。

簡易チェック

  • アプリを完全に終了してから再起動します。
  • アプリがエラー画面を表示している場合は、Restart をクリックしてエラー詳細をコピーします。
  • macOS のみ:OpenCode メニュー -> Reload 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 が再構築できるようにします。

  1. OpenCode Desktop を完全に終了します。
  2. キャッシュディレクトリを削除します。
  • macOS:Finder -> Cmd+Shift+G -> ~/.cache/opencode を貼り付け
  • Linux:~/.cache/opencode を削除 (または rm -rf ~/.cache/opencode を実行)
  • Windows:WIN+R を押して %USERPROFILE%\.cache\opencode を貼り付け
  1. OpenCode Desktop を再起動します。

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

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

“Connection Failed” ダイアログが表示される場合 (またはアプリがスプラッシュ画面から進まない場合)、カスタムサーバー URL を確認してください。

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

ホーム画面から、サーバー名 (ステータスドット付き) をクリックしてサーバーピッカーを開きます。Default server セクションで Clear をクリックします。

設定から 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 内から設定を消去できない場合は、デスクトップアプリの保存状態をリセットします。

  1. OpenCode Desktop を終了します。
  2. 以下のファイルを見つけて削除します (これらは 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 で問題が発生している場合は、次の手順に従ってください。

  1. GitHub で issue を報告する

    バグの報告や機能のリクエストの最適な方法は、GitHub リポジトリ経由です。

    github.com/anomalyco/opencode/issues

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

  2. Discord に参加する

    リアルタイムのヘルプやコミュニティでの議論については、Discord サーバーに参加してください。

    opencode.ai/discord

一般的な問題

ここでは、一般的な問題とその解決方法を紹介します。

OpenCode が起動しない

  1. ログでエラーメッセージを確認する
  2. --print-logs を指定して実行し、ターミナルで出力を確認する
  3. opencode upgrade で最新バージョンであることを確認する

認証の問題

  1. TUI で /connect コマンドを使って再認証する
  2. API キーが有効であることを確認する
  3. ネットワークが Provider の API への接続を許可していることを確認する

モデルが利用できない

  1. Provider で認証済みであることを確認する
  2. 設定内のモデル名が正しいことを確認する
  3. 一部のモデルは特定のアクセス権やサブスクリプションが必要な場合がある

ProviderModelNotFoundError が発生した場合は、ほとんどの場合、モデルの参照が誤っています。 モデルは <providerId>/<modelId> のように参照してください。

例:

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

利用可能なモデルを確認するには、opencode models を実行してください。

ProviderInitError

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

解決するには:

  1. まず、providers ガイド に従って Provider が正しく設定されていることを確認します

  2. 問題が解決しない場合は、保存されている設定をクリアしてみてください。

    rm -rf ~/.local/share/opencode

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

  3. TUI で /connect コマンドを使って Provider と再認証します。

AI_APICallError と Provider パッケージの問題

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

Provider パッケージの問題を解決するには:

  1. Provider パッケージのキャッシュをクリアします。

    rm -rf ~/.cache/opencode

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

  2. opencode を再起動して最新の Provider パッケージを再インストールします。

これにより opencode は Provider パッケージの最新バージョンをダウンロードし、モデルパラメータや 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 の順でクリップボードツールを探します。