OpenCode DesktopとCLIはどう使い分ける?設定と切り替えの確認点

OpenCode DesktopとCLIを作業別に比較。モデルの接続、セッションの引き継ぎ、バージョン差によるエラーを解説し、試せるPythonの練習課題も提供します。

OpenCode DesktopとCLIはどう使い分ける?設定と切り替えの確認点

セッションやコードの変更を視覚的に確認したいなら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で同じ指示を繰り返すCLIopencode runなら対話画面を開かずに実行できるモデル、権限、出力処理、失敗時のステータス
キーボード操作を中心に対話するCLI TUICLIはスクリプト用のコマンドだけでなく対話アプリでもあるターミナル表示と選択中のプロジェクト
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のドキュメントにある手順は次のとおりです。

  1. Settings → Providersを開き、Show more providersを選びます。
  2. Ofoxを検索し、接続してキーを入力します。
  3. Settings → ModelsでOfoxを検索し、使うモデルを有効にします。
  4. 正しいプロジェクトでセッションを作り、そのモデルをセッションのモデル選択欄で選びます。

実際の画面が違う場合は、アカウントに問題があると判断する前に、インストール済みの版と現在のプロバイダー設定を確認します。下の画像は英語のOfoxドキュメントを記録したもので、今回Desktopで推論を実行した画面ではありません。

Desktopのプロバイダー設定経路を示す英語のOfoxドキュメント

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などを拒否することです。対象を絞った練習であり、ソフトウェア開発能力のベンチマークではありません。

  1. アーカイブを2回展開し、desktop-checkとcli-checkなどの別フォルダーに置きます。
  2. それぞれでpython3 -m unittest -vを実行します。Python 3をpythonで起動する環境では、そのコマンドを使います。
  3. 初期状態では4テスト中2つが失敗するはずです。エージェントを使う前にこの基準を記録します。
  4. Desktopでdesktop-checkを開き、cli-checkからCLIを起動します。プロバイダー、モデル、権限条件をそろえます。
  5. 両方に同じ指示を与えます。下は配布物と同じ英語の指示で、関数だけの修正、テストの維持、実際の結果報告を求めています。
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、モデルIDDesktopの有効化とCLI一覧を確認。カスタムなら登録も確認
DesktopにあるセッションがCLIにないプロジェクトパス、アカウント、サーバー正しいプロジェクトで一覧を表示し、サービス状態を確認
401が返る認証情報の取得元と宛先エンドポイントOfoxの認証・リクエストエラーガイドを使い、障害報告に秘密情報を貼らない
429が返るレート制限と返された再試行情報429の再試行ガイドを確認。画面を変えても制限はなくならない
チャットは動くがツールが失敗するモデル能力、プロトコル、ツール結果の形式OpenAI互換APIの確認手順で通常チャットとツール呼び出しの互換性を分ける

更新後の問題なら、旧版・新版と最初に失敗した操作を記録し、変数を1つずつ変えます。再インストール、キーの交換、プロバイダー設定の書き換えを同時に行うと、どの変更が効いたのか分かりにくくなります。

ローカルで視覚的にレビューするならDesktop、ターミナルやスクリプト中心ならCLIから始めましょう。引き継ぎが役立つ場合に両方を使えば十分です。成功の基準は、正しいファイル・モデル・権限で、自分でも検証できる結果を得られたかどうかです。