OpenCode DesktopとCLIはどう使い分ける?設定と切り替えの確認点
OpenCode DesktopとCLIを作業別に比較。モデルの接続、セッションの引き継ぎ、バージョン差によるエラーを解説し、試せるPythonの練習課題も提供します。
セッションやコードの変更を視覚的に確認したいならOpenCode Desktop、ターミナル、リモートシェル、繰り返し実行するスクリプトから作業を始めるならCLIが出発点になります。 両方を使うこともできます。ただし、同じアカウントで接続するだけでなく、プロジェクトのフォルダー、サーバー、モデルを合わせることが大切です。
この記事はOpenCodeの2つのインターフェースを比較します。OpenAIのCodexとの比較を探している場合は、OpenCodeとCodex CLIの比較を参照してください。
2026年11月17日に現行ドキュメントを確認し、隔離したディレクトリにOpenCode CLI 2.3.0をインストールしてバージョンとヘルプ出力を検証しました。配布する練習課題のPythonテストもローカルで実行しています。有料モデルの比較や、Desktop上での課題実行は行っていません。 以下の画面動作はドキュメントに基づくもので、どちらが優れたコードを生成するかを実測した結果ではありません。この記事はAPI接続サービスを提供するOfoxが公開しています。
終わらせたい作業から選ぶ
| 次に行う作業 | 最初に使うもの | 理由 | 確認すること |
|---|---|---|---|
| ローカルリポジトリを調べ、複数の変更を確認する | Desktop | セッションと差分を視覚的に扱う流れがレビュー中心の作業に合う | 意図したフォルダーを開き、受け入れる前に変更ファイルを見る |
| SSHで開発用マシンに接続して作業する | CLI | 既存のリモートシェルから始められる | 認証情報、ファイル、ツールがそのマシンにあること |
| スクリプトやCIで同じ指示を繰り返す | CLI | opencode runなら対話画面を開かずに実行できる | モデル、権限、出力処理、失敗時のステータス |
| キーボード操作を中心に対話する | CLI TUI | CLIはスクリプト用のコマンドだけでなく対話アプリでもある | ターミナル表示と選択中のプロジェクト |
| 1つのローカル作業の途中で画面を切り替える | どちらでもよいが、明示的に引き継ぐ | 現行V2は共有ローカルサーバーに対応 | 両方が実際に同じサーバーとプロジェクトを使うこと |
| 認証やプロバイダーのエラーを直す | 先に接続を診断する | 画面を変えても無効なキーや非対応のリクエストは直らない | 正確なプロバイダー、モデル、エンドポイント、エラー |
OpenCodeの製品ページ(英語)では、Desktopはセッション、タブ、差分を備えたワークスペース、Terminalはシェルやリモートサーバーから使えるインターフェースとして紹介されています。作業方法の違いとして役立ちますが、基盤モデルの能力が異なる証拠ではありません。
たとえば、SSH上でテストの失敗を調べている開発者が、ファイルシステムの異なるローカルGUIに移っても便利になるとは限りません。一方、複数のローカル変更をレビューするなら、会話と差分を同じ視覚的な作業領域で見たい場合があります。どちらを選んでも、プロジェクトのテストは必要です。
設定手順を試す前にバージョンを確認する
「DesktopかCLIか」と「OpenCode 1かOpenCode 2か」は別の比較です。バージョンの不一致が、インターフェースの制約に見えることがあります。
ターミナルで次を実行します。
opencode --version
opencode --help
opencode run --help
隔離環境ではopencode v2.3.0が返り、ヘルプにrun、session、service、models、auth、debugが表示されました。この版のopencode modelsにはプロバイダー名の位置引数がありません。古い記事のコマンドが現行バイナリでも使えるとは限りません。
macOSまたはLinuxにnpmでV2を新規インストールする場合、現行のインストール文書(英語)には次の手順があります。
npm install -g @opencode/cli
opencode --version
V1を使っている場合は、先に公式移行ガイド(英語)を確認してください。両世代ともopencodeコマンドを使うため、別のパッケージをそのまま追加すると既存コマンドを置き換えたり競合したりする可能性があります。Windowsでは、パッケージマネージャーの手順が適用できると考えず、OpenCodeが案内するスタンドアロンCLIのダウンロードを使います。DesktopもmacOS、Windows、Linux向けに提供されています。
V2はサポート対象のV1設定を引き続き扱えるため、導入時に全ファイルを書き直す必要はありません。ただし、プラグインとサーバー連携には破壊的変更があります。V2ネイティブのプロバイダー設定はproviders、package、settings、旧形式はprovider、npm、optionsを使います。検索結果の断片を組み合わせず、入れ子になった各プロバイダーの項目を1つの形式で統一してください。動いている設定を変換する前にはバックアップを残します。
プロバイダーに接続し、モデルを選ぶ
確認点は3つあります。プロバイダーに接続できること、モデルが表示されること、リクエストが実際に成功することです。最初の確認だけでは、残り2つの成功は証明できません。
Ofoxでは、両画面の経路を説明するOpenCode接続手順から始めます。APIキーの認証ガイドでキーを取得し、コミットするプロジェクトファイル、スクリーンショット、コピーする診断ログには含めないでください。
Desktopの経路
Ofoxのドキュメントにある手順は次のとおりです。
- Settings → Providersを開き、Show more providersを選びます。
- Ofoxを検索し、接続してキーを入力します。
- Settings → ModelsでOfoxを検索し、使うモデルを有効にします。
- 正しいプロジェクトでセッションを作り、そのモデルをセッションのモデル選択欄で選びます。
実際の画面が違う場合は、アカウントに問題があると判断する前に、インストール済みの版と現在のプロバイダー設定を確認します。下の画像は英語のOfoxドキュメントを記録したもので、今回Desktopで推論を実行した画面ではありません。

2026年11月17日に取得したドキュメントのスクリーンショット。埋め込まれた画面は文書内の例であり、利用者のインストール済みバージョンを示すものではありません。
CLIの経路
プロジェクトのディレクトリを開き、opencodeを起動し、/connectでプロバイダー、/modelsでモデルを選びます。これらのスラッシュコマンドは対話画面内で入力するもので、通常のシェルプロンプトに入力するものではありません。
スクリプトではopencode modelsでモデル一覧を確認し、返された正確な識別子を使います。
opencode run --model 'PROVIDER/MODEL' "Explain the files in this project. Do not edit them."
PROVIDER/MODELは実在するモデルではなく、置換が必要なプレースホルダーです。英語の指示は「プロジェクトのファイルを説明し、編集しないでください」という内容です。このコマンドはモデルへリクエストを送り、プロバイダーの料金が発生する可能性があります。今回はローカルのヘルプで引数を確認しただけで、リクエストは実行していません。
要件に合うなら、組み込みのOfoxプロバイダーを使います。カスタムプロバイダーは特定のプロトコルやエンドポイント向けの別経路で、Desktopを使うための必須条件ではありません。組み込みとカスタムの違いを確認してください。カスタム経路が必要なら、現行のOpenCodeプロバイダーリファレンス(英語)と、Ofox文書の正確なエンドポイント・対応プロトコルを照合します。カスタムAPI設定ガイド(英語)ではプロバイダーとモデル登録の関係を説明していますが、日付付きの版別サンプルは実際のインストール版と照合する必要があります。
切り替えるとき、何が共有されるのか
現行のCLIドキュメント(英語)は、ローカルユーザー向けの共有バックグラウンドサーバーを説明しています。セッション、設定、権限、連携、ツール実行をサーバーが管理します。CLIは--standaloneで専用サーバーを使ったり、--serverで指定サーバーへ接続したりすることもできます。
そのため「同じノートPCを使っている」だけでは引き継ぎの確認として不十分です。専用サーバー、別アカウント、リモートホスト、異なるプロジェクトパスでは、作業のコンテキストも変わり得ます。
| 項目 | 引き継ぎ時の確認 | 理由 |
|---|---|---|
| ファイル | プロジェクトの絶対パスと現在のファイル内容を合わせる | 同名フォルダーでも作業内容は異なる場合がある |
| サーバー | 両クライアントの接続先が意図したサービスか確認する | 専用・リモートサービスはローカル共有サービスと自動的に同一にはならない |
| セッション | 最新のものではなく、続けたいセッションを選ぶ | 最近の履歴が別の作業の場合がある |
| モデル | プロバイダーとモデルの正確な選択を比較する | 表示名が似ていても同じ経路とは限らない |
| 権限 | 読み取り、編集、実行の許可範囲を確認する | 画面の切り替えはアクセス拡大の許可ではない |
| ツールと環境 | 実際に処理が行われるマシンのツールを確認する | ローカルのPythonがリモートにも存在するとは限らない |
進行中の作業を再起動せずにサービス状態を調べるには、次を使います。
opencode service status
opencode session list
セッションのコマンドは、続ける予定のプロジェクト内で実行します。CLI 2.3.0のローカルヘルプでは、現在のプロジェクトのトップレベルセッションを列挙すると説明されています。確認したのはコマンドの定義であり、画面間のセッション移行を実測したわけではありません。
設定が食い違う場合は、設定リファレンス(英語)に沿って、関連するプロジェクト設定とユーザー設定の場所を確認します。管理対象の設定が優先されることもあります。画面の動作をそろえるために管理ポリシーを無効にしないでください。
別々の作業コピーで同じ小さな課題を試す
比較用の練習課題をダウンロードできます。意図的に未完成にしたPython関数、4つのテスト、指示文、編集者が書いた参考解答が入っています。説明と指示文は英語です。テスト自体の実行にAPIキーや依存パッケージのインストールは必要ありません。
課題は、大文字・小文字を区別せずに.csvで終わるファイル名を受け入れ、.csv.tmpなどを拒否することです。対象を絞った練習であり、ソフトウェア開発能力のベンチマークではありません。
- アーカイブを2回展開し、
desktop-checkとcli-checkなどの別フォルダーに置きます。 - それぞれで
python3 -m unittest -vを実行します。Python 3をpythonで起動する環境では、そのコマンドを使います。 - 初期状態では4テスト中2つが失敗するはずです。エージェントを使う前にこの基準を記録します。
- Desktopで
desktop-checkを開き、cli-checkからCLIを起動します。プロバイダー、モデル、権限条件をそろえます。 - 両方に同じ指示を与えます。下は配布物と同じ英語の指示で、関数だけの修正、テストの維持、実際の結果報告を求めています。
Read app.py and test_app.py. Update only accepts_csv in app.py so filenames
ending in .csv are accepted case-insensitively. Reject .csv.tmp and names
with no .csv suffix. Do not modify the tests or install dependencies.
Run python3 -m unittest -v and report the result. If Python is unavailable,
say so rather than claiming the tests passed. Explain the exact code change.
実行後にapp.pyを確認し、test_app.pyが変更されていないことを確かめます。自分でもテストを再実行し、4つすべての成功を確認してください。「直しました」という回答だけでは合格ではありません。参考解答は意図したルールを確かめるためのもので、どちらかのOpenCode画面が生成した出力ではありません。
ローカルでは、初期状態の2件の失敗と参考解答の4件の成功を確認しました。DesktopとCLIの所要時間、料金、モデルの成功率は収集していません。自分で試す場合も、それらの観察と確定的なテスト結果を分けて記録します。小さな課題で操作の相性は確認できますが、一方が常に高速・高精度だとは証明できません。
引き継ぎを試す場合は、進行中の作業を止め、画面を切り替え、前の表の6項目を確認してから続けます。比較中に2つのエージェントから同じ作業コピーを同時編集すると、変更が混ざって結果を解釈できなくなります。
失敗している箇所を切り分ける
| 症状 | 最初の確認 | 次の対応 |
|---|---|---|
opencodeが見つからない | インストールとシェルのPATH | 選んだ版の導入方法を確認。PATH変更後はシェルを開き直す |
| コピーしたコマンドが引数を拒否する | opencode --versionと該当コマンドの--help | 認証情報を変える前にインストール世代に合う構文を使う |
| 接続済みなのにモデルがない | モデル表示、プロバイダーID、モデルID | Desktopの有効化とCLI一覧を確認。カスタムなら登録も確認 |
| DesktopにあるセッションがCLIにない | プロジェクトパス、アカウント、サーバー | 正しいプロジェクトで一覧を表示し、サービス状態を確認 |
| 401が返る | 認証情報の取得元と宛先エンドポイント | Ofoxの認証・リクエストエラーガイドを使い、障害報告に秘密情報を貼らない |
| 429が返る | レート制限と返された再試行情報 | 429の再試行ガイドを確認。画面を変えても制限はなくならない |
| チャットは動くがツールが失敗する | モデル能力、プロトコル、ツール結果の形式 | OpenAI互換APIの確認手順で通常チャットとツール呼び出しの互換性を分ける |
更新後の問題なら、旧版・新版と最初に失敗した操作を記録し、変数を1つずつ変えます。再インストール、キーの交換、プロバイダー設定の書き換えを同時に行うと、どの変更が効いたのか分かりにくくなります。
ローカルで視覚的にレビューするならDesktop、ターミナルやスクリプト中心ならCLIから始めましょう。引き継ぎが役立つ場合に両方を使えば十分です。成功の基準は、正しいファイル・モデル・権限で、自分でも検証できる結果を得られたかどうかです。


