日本語
ドキュメント
トラブルシューティング

トラブルシューティング

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

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 CLI をアンインストールして関連ファイルを削除するには、次を実行します:

opencode uninstall

このコマンドは削除される内容を表示し、確認を求めます。設定やアプリケーションデータを残すオプションについては、CLI リファレンスを参照してください。

OpenCode Desktop を削除するには、お使いの OS のアプリ管理ツールを通じてアプリケーションをアンインストールしてください。

デスクトップアプリ

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 はディスクからローカルプラグインを読み込むこともできます。これらを一時的に移動（またはフォルダ名を変更）してデスクトップアプリを再起動します:

  • Global plugins

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

  • Project 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 を削除する

Home 画面から、サーバー名（ステータスドット付き）をクリックして Server picker を開きます。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 で問題を報告する バグの報告や機能のリクエストには、当社の GitHub リポジトリを使うのが最善の方法です: github.com/anomalyco/opencode/issues (opens in a new tab) 新しい issue を作成する前に、既存の issue を検索して、あなたの問題が既に報告されていないか確認してください。
  2. Discord に参加する リアルタイムのヘルプとコミュニティでの議論には、当社の Discord サーバーに参加してください: opencode.ai/discord (opens in a new tab)

よくある問題

ここでは、よくある問題とその解決方法を紹介します。

OpenCode が起動しない

  1. ログにエラーメッセージがないか確認します
  2. --print-logs を付けて実行し、ターミナルに出力を表示してみます
  3. opencode upgrade で最新バージョンになっていることを確認します

認証の問題

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

モデルを利用できない

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

ProviderModelNotFoundError が発生する場合は、どこかでモデルを正しく参照できていない可能性が高いです。 モデルは次のように参照する必要があります: <providerId>/<modelId>

例:

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

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

ProviderInitError

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

これを解決するには:

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

  2. 問題が解決しない場合は、保存された設定をクリアしてみます:

    rm -rf ~/.local/share/opencode

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

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

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

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

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

  1. プロバイダーパッケージのキャッシュをクリアします:

    rm -rf ~/.cache/opencode

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

  2. 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 の順にクリップボードツールを探します。

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

文書の出典（MIT）