---
title: トラブルシューティング
description: よくある問題とその解決方法。
---

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` を貼り付けます

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

```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` を貼り付けます

3. 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 でパフォーマンスの低下、ファイル アクセスの問題、またはターミナルの問題が発生している場合は、[WSL (Windows Subsystem for Linux)](/docs/windows-wsl) を使用してみてください。 WSL は、OpenCode の機能とよりシームレスに連携する Linux 環境を提供します。

---

### 通知が表示されない

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

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

---

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

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

1. OpenCode デスクトップを終了します。
2. これらのファイルを見つけて削除します (これらのファイルは 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 で問題が発生している場合:

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

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

[**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues)

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

2. **Discord に参加してください**

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

[**opencode.ai/discord**](https://opencode.ai/discord)

---

## よくある問題

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

---

### 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. まず、[プロバイダー ガイド](/docs/providers) に従って、プロバイダーが正しく設定されていることを確認します。
2. 問題が解決しない場合は、保存されている構成をクリアしてみてください。

   ```bash
   rm -rf ~/.local/share/opencode
   ```

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

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

---

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

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

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

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

   ```bash
   rm -rf ~/.cache/opencode
   ```

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

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

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

---

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

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

**X11 システムの場合:**

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

**Wayland システムの場合:**

```bash
apt install -y wl-clipboard
```

**ヘッドレス環境の場合:**

```bash
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` の順序でクリップボード ツールを検索しようとします。
