Troubleshooting

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

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

Logs

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

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 のように。

Storage

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/ に保存されます

Desktop app

OpenCode Desktop は、ローカルの OpenCode サーバー（opencode-cli サイドカー）をバックグラウンドで実行します。ほとんどの問題は、不具合のあるプラグイン、破損したキャッシュ、または不適切なサーバー設定が原因です。

Quick checks

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

Disable plugins

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

Check the global config

グローバル設定ファイルを開き、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": [],
}

Check plugin directories

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

Global plugins
- macOS/Linux : ~/.config/opencode/plugins/
- Windows : WIN+R を押して %USERPROFILE%\.config\opencode\plugins を貼り付けます
Project plugins （プロジェクトごとの設定を使う場合のみ）
- <your-project>/.opencode/plugins/

アプリが再び動作するようになったら、プラグインを 1 つずつ再度有効にして、どれが問題の原因かを特定します。

Clear the cache

プラグインの無効化が役に立たない場合（またはプラグインのインストールが止まっている場合）は、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 を再起動します。

Fix server connection issues

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

"Connection Failed" ダイアログが表示される場合（またはアプリがスプラッシュ画面から先に進まない場合）は、カスタムサーバー URL を確認します。

Clear the desktop default server URL

Home 画面から、サーバー名（ステータスドット付き）をクリックして Server picker を開きます。Default server セクションで Clear をクリックします。

Remove `server.port` / `server.hostname` from your config

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

Check environment variables

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

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

Linux: Wayland / X11 issues

Linux では、一部の Wayland 構成で空白のウィンドウやコンポジターのエラーが発生することがあります。

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

Windows: WebView2 runtime

Windows では、OpenCode Desktop は Microsoft Edge の WebView2 Runtime を必要とします。アプリが空白のウィンドウで開いたり起動しなかったりする場合は、WebView2 をインストール/更新してから再試行してください。

Windows: General performance issues

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

Notifications not showing

OpenCode Desktop がシステム通知を表示するのは次の場合のみです:

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

Reset desktop app storage (last resort)

アプリが起動せず、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% （その後、上記のファイル名を検索します）

Getting help

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)

Common issues

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

OpenCode won't start

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

Authentication issues

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

Model not available

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

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 and provider package issues

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

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

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

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

Copy/paste not working on 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)