インストール - OpenCode

提供: MochiuWiki : SUSE, EC, PCB

2026年5月9日 (土) 10:10時点におけるWiki (トーク | 投稿記録)による版 (→Step 4 : ビルドの実行)

概要

OpenCodeは、オープンソースのAIコーディングエージェントである。
ターミナルベースのTUI (ターミナルユーザーインターフェース) を提供し、75以上のLLMプロバイダに対応している。

主要な特徴として、以下が挙げられる。

  • Anthropic (Claude)、OpenAI (GPT)、Google (Gemini)、GitHub Copilot、Ollama等のモデルの主要プロバイダをサポート
  • 2026年1月にGitHub Copilotとの公式パートナーシップを発表
  • プライバシー重視の設計
    コードは送信されず、ローカルでの処理を優先
  • CLI、TUI、Desktop アプリ、IDE拡張機能、Webインターフェースを提供
  • MCP (Model Context Protocol) とLSP (Language Server Protocol) をサポート
  • 組み込みエージェント
    • build (開発用)
    • plan (読み取り専用分析)


OpenCodeは、Go言語でBubble Tea TUIフレームワークを使用して実装されている。
セッション管理、マルチセッション対応を備え、会話履歴の保存、復元、エクスポートが可能である。

Desktop アプリはElectronベースのネイティブアプリケーションとして実装されており、TypeScriptで実装された内部CLI、SolidJS + Viteで構築されたフロントエンドを組み合わせている。


主な機能

OpenCodeは、多様な機能を提供する包括的なAIコーディングツールである。

主要機能一覧
機能 説明
TUI (Bubble Tea) ターミナルベースの対話型インターフェース
マルチプロバイダ対応 75以上のLLMプロバイダをサポート
セッション管理 会話履歴の保存、復元、エクスポート
ツール統合 ファイル操作、Bash実行、テスト実行等
MCP (Model Context Protocol) 外部ツールとの統合プロトコル
LSP (Language Server Protocol) 25以上の組み込みLSPサーバーによる言語サーバーとの連携
組み込みエージェント build (開発用)
plan (読み取り専用分析)
general (調査用)
explore (コード探索用)
Desktop アプリ Electronベースのネイティブアプリ
IDE拡張機能 VS Code、JetBrains等のIDE拡張
カスタムコマンド .opencode/commands/ ディレクトリ内でユーザ定義コマンド作成
Git統合 /undo、/redo コマンドでGitバック付きの変更管理



対応AIプロバイダとモデル

OpenCodeは、75以上のLLMプロバイダに対応している。

主要プロバイダ一覧

主要プロバイダ一覧
プロバイダ 認証方法 備考
Anthropic APIキー (ANTHROPIC_API_KEY) Claude 4.x系をサポート
OpenAI APIキー (OPENAI_API_KEY) GPT-4o、o3等をサポート
Google APIキー (GOOGLE_API_KEY) Gemini 3等をサポート
GitHub Copilot GitHub認証 (OAuth) /connect コマンドで認証
Z.AI APIキー GLM-5、GLM-4.7等をサポート
GLM Coding Plan対応
AWS Bedrock AWS認証情報 Anthropicモデルのホスティング
Azure OpenAI Azureエンドポイント OpenAIモデルのホスティング
Ollama ローカル実行 (認証不要) ローカルモデルの実行
OpenRouter APIキー 複数プロバイダのルーティング
Groq APIキー 高速推論
Together AI APIキー オープンソースモデル
Fireworks AI APIキー 高速推論


推奨モデル

用途別推奨モデル
用途 推奨モデル
高精度コーディング Claude Sonnet 4.5、GPT-4o
高速処理 Claude Haiku 4.5、Gemini 2.5 Flash
複雑な推論 Claude Opus 4.6、o3
ローカル実行 Qwen 2.5 Coder (Ollama)
コスト効率重視 GLM-4.7、GLM-5 (Z.AI Coding Plan)


ローカルモデル (Ollama)

Ollamaを使用することで、ローカル環境でモデルを実行できる。

Ollamaのインストール

Ollamaの公式サイトからインストールスクリプトをダウンロードして実行する。

curl -fsSL https://ollama.com/install.sh | bash


モデルのダウンロード

Ollamaでモデルをダウンロードする。

ollama pull qwen2.5-coder


OpenCodeでの設定

opencode.json でOllamaプロバイダを設定する。

 {
   "$schema": "https://opencode.ai/config.json",
   "model": "ollama/qwen2.5-coder"
 }



前提条件

OpenCodeをインストールするには、以下の前提条件を満たす必要がある。

標準インストール時の前提条件

標準インストール時の前提条件
要件 詳細
OS Linux、MacOS、Windows
Node.js npm経由のインストールに必要 (Node.js 18以上)
ネットワーク AIプロバイダへの接続に必要
AIプロバイダのAPIキー 使用するプロバイダのAPIキーまたは認証情報



インストール

OpenCodeのインストール方法を以下に示す。

クイックインストール (Linux)

公式のインストールスクリプトを使用してインストールする。

curl -fsSL https://opencode.ai/install | bash



Homebrew (MacOS)

Homebrewを使用してインストールできる。

brew install opencode



npm (全プラットフォーム)

npmを使用してグローバルインストールする。

npm install -g opencode



Windows (Scoop / Chocolatey)

Windowsでは、ScoopまたはChocolateyを使用してインストールできる。

Scoopでのインストール
scoop install opencode


Chocolateyでのインストール
choco install opencode



デスクトップアプリケーション

OpenCodeの公式Webサイトにアクセスして、デスクトップアプリケーションをダウンロードする。

対応プラットフォーム:

  • Linux (deb、rpm)
  • MacOS (dmg)
  • Windows (exe)



バージョン確認

インストール後、バージョンを確認する。

opencode --version



初期設定

OpenCodeの初期設定を以下に示す。

プロバイダの認証

OpenCodeの初回起動時に、/connect コマンド または opencode auth login コマンドでAIプロバイダとの認証を設定する。

GitHub Copilotとの連携

OpenCodeはGitHub Copilotの公式パートナーであり、/connect コマンドで認証を設定できる。

OpenCodeを起動する。

opencode


認証を設定する。

/connect


例えば、GitHub Copilotを選択する。
Webブラウザが開き、GitHub認証ページが表示される。

認証を完了すると、OpenCodeでGitHub Copilotが使用可能になる。


APIキーによる認証

環境変数でAPIキーを設定する方法もある。

 export ANTHROPIC_API_KEY="sk-..."
 export OPENAI_API_KEY="sk-..."
 export GOOGLE_API_KEY="..."


環境変数を永続化する場合は、~/.profileファイル等に環境変数 ANTHROPIC_API_KEY を設定する。

 export ANTHROPIC_API_KEY="sk-..."



Z.AI (GLM) との連携

Z.AIのGLMモデル (GLM-5、GLM-4.7等) をOpenCodeで使用するには、Z.AI GLM または GLM Coding Planのサブスクリプション契約およびAPIキーが必要である。

GLM / GLM Coding Planの概要

GLM / GLM Coding Planは、Z.AIが提供するAIコーディング向けのサブスクリプションプランである。

GLM Coding Plan
プラン 月額 GLM-5対応 5時間あたりの目安
Lite $10 対応 約80プロンプト
Pro $30 対応 約400プロンプト
Max $120 対応 約1,600プロンプト


使用可能なモデルは以下の通りである。

  • GLM-5 (ProプランおよびMaxプランのみ)
  • GLM-4.7
  • GLM-4.6
  • GLM-4.5
  • GLM-4.5-Air


GLM-5はピーク時 (日本時間 15:00〜19:00) に3倍、オフピーク時に2倍のクォータを消費する。
日常的なタスクにはGLM-4.7を使用し、複雑なタスクにのみGLM-5を使用することが推奨される。

認証の設定手順

Z.AIのAPIコンソールにアクセスして、APIキーを取得する。

opencode auth login コマンドを実行して、プロバイダ選択で Z.AI Coding Plan を選択する。

 opencode auth login



┌  Add credential
│
◆  Select provider
│  ● Z.AI Coding Plan
│  ...
└


Z.AIのAPIキーを入力する。

┌  Add credential
│
◇  Select provider
│  Z.AI Coding Plan
│
◇  Enter your API key
│  <Z.AIのAPIキーを入力>
└


OpenCodeを起動して、/models コマンドでGLM-5 / GLM-4.7等のモデルを選択する。

opencode



/models



トラブルシューティング : Insufficient balance

GLMモデルの使用時に、以下に示すエラーメッセージが表示される場合がある。

Insufficient balance or no resource package. Please recharge.


このエラーは、OpenCodeのプロバイダ設定がGLM Coding Plan専用のエンドポイントに接続されていない場合に発生する。

GLM Coding Planでは、専用のAPIエンドポイント (https://api.z.ai/api/coding/paas/v4) を使用する必要がある。
プロバイダ選択で Z.AI (通常のAPI) を選択した場合、標準エンドポイント (https://api.z.ai/api/paas/v4) に接続されるため、Coding Planの残高が認識されず、上記のエラーが発生する。

Z.AI APIエンドポイントの違い
エンドポイント URL 用途
標準 (通常API) https://api.z.ai/api/paas/v4 従量課金のAPI利用
Coding Plan専用 https://api.z.ai/api/coding/paas/v4 GLM Coding Planサブスクリプション利用


対処方法として、一旦Z.AIの認証情報をログアウトしてから、Z.AI Coding Plan で再度ログインする。

Z.AIの認証情報をログアウトする。

 opencode auth logout


再度ログインして、プロバイダ選択で Z.AI Coding Plan を選択する。

 opencode auth login



┌  Add credential
│
◆  Select provider
│  ● Z.AI Coding Plan    ← Z.AI ではなく、Z.AI Coding Planを選択すること
│  ...
└


APIキーを入力して認証を完了した後、OpenCodeを起動して正常にGLMモデルが使用できることを確認する。


設定ファイル

OpenCodeの設定ファイルは、プロジェクトルート または ホームディレクトリ に配置する。

設定ファイルの場所

設定ファイルは以下の順序で検索される。

  • プロジェクトルート
    opencode.json
  • ホームディレクトリ
    ~/.opencode/config.json



設定ファイルの例
 {
   "$schema": "https://opencode.ai/config.json",
   "model": "anthropic/claude-sonnet-4-5-20250929",
   "small_model": "anthropic/claude-haiku-4-5-20251001",
   "keybinds": {
      "leader": "ctrl+x"
   }
 }


設定可能な項目を以下に示す。

  • model
    使用するモデル名 (プロバイダ/モデル名 形式)
    例: anthropic/claude-sonnet-4-5-20250929、openai/gpt-4o
  • small_model
    軽量タスク用のモデル (コスト削減に有効)
    例: anthropic/claude-haiku-4-5-20251001
  • keybinds.leader
    リーダーキーの設定
    デフォルト : ctrl+x



CLIコマンド

OpenCodeは、CLIモードと対話モードの両方で使用できる。

主要コマンド

主要コマンド一覧
コマンド 説明
opencode TUIを起動
opencode run "プロンプト" 非対話モードでプロンプトを実行
opencode --model プロバイダ/モデル名 モデルを指定して起動
opencode --continue 前回のセッションを継続して起動
opencode auth login プロバイダの認証を設定
opencode auth logout 認証情報を削除
opencode models 使用可能なモデル一覧を表示
opencode mcp list MCPサーバ一覧を表示
opencode mcp add サーバー名 MCPサーバを追加
opencode serve ヘッドレスバックエンドサーバを起動
opencode --version バージョンを表示
opencode --help ヘルプを表示


非対話モード

非対話モードでは、プロンプトをコマンドライン引数として渡すことができる。

使用例

プロジェクトの概要を説明する。

opencode run "このプロジェクトの概要を説明して"


モデルを指定してテストを実行する。

opencode run "テストを実行して" --model anthropic/claude-sonnet-4-5-20250929



TUI (ターミナルユーザーインターフェース)

OpenCodeのTUIは、ターミナルベースの対話型インターフェースである。

スラッシュコマンド

TUI内でスラッシュコマンドを使用して、様々な操作を実行できる。

スラッシュコマンド一覧
コマンド 説明
/new 新しいセッションを開始
/init プロジェクト構造を分析
/undo 直前の変更を元に戻す (Git連携)
/redo 元に戻した変更をやり直す
/compact 会話を要約して圧縮
/share 会話の共有リンクを生成
/export 会話をMarkdownでエクスポート
/sessions 過去のセッション一覧を表示
/models 使用可能なモデル一覧を表示
/agents エージェント一覧を表示
/connect プロバイダ認証を設定
/status 現在のステータスを表示
/mcp MCPサーバ一覧を表示
/theme テーマを変更
/editor 外部エディタで入力
/help ヘルプを表示
/commands コマンド一覧を表示
/exit OpenCodeを終了


キーバインド

OpenCodeのリーダーキーのデフォルトは、[Ctrl] + [X]キーである。
リーダーキーを押した後に各キーを入力する。

キーバインド一覧
キー 説明
[Ctrl] + [X] -> [N] 新しいセッション
[Ctrl] + [X] -> [L] セッション一覧
[Ctrl] + [X] -> [T] タイムライン
[Ctrl] + [X] -> [M] モデル選択ダイアログ
[Ctrl] + [X] -> [C] コンパクト表示
[Ctrl] + [P] コマンドパレット
[Tab] Plan/Buildエージェント切替
[Page Up] / [Page Down] スクロール
[Shift] + [Enter] 改行入力


ファイル参照とBashコマンド

TUI内でファイル参照とBashコマンドの実行ができる。

ファイル参照

@ でファイルをファジー検索して参照を追加する。

@filename


Bashコマンドの実行

! をプレフィックスとしてBashコマンドを実行する。

!ls -la
!git status



CLIバイナリのビルド

ビルドの前提条件

ビルドの前提条件
項目 要件
Bun 1.3.13以上
(リポジトリルートの package.json 内の packageManager フィールドで bun@1.3.13 が指定されている)
git 必須ではない。
(packages/script/src/index.ts 内で git branch --show-current が呼び出されるが、環境変数で回避可能)
ネットワーク ビルド時に https://models.dev/api.json からモデル定義を取得
ディスク空き容量 約3[GB]以上 (依存パッケージ + バイナリ約150[MB])


前提条件の確認コマンド
# Bunバージョン確認 (1.3.13以上が必要)
bun --version

# ネットワーク接続の確認
curl -s https://models.dev/api.json | head -c 100


ビルド方式の説明

ビルド方式の説明
項目 内容
言語 TypeScript (Bunランタイム)
ビルド方式 Bun.build() の compile オプションでスタンドアロン実行ファイルを生成
ビルドスクリプト packages/opencode/script/build.ts
出力 Bunランタイムを内蔵した単一バイナリ (opencode)
出力先 packages/opencode/dist/opencode-linux-x64/bin/opencode
バイナリサイズ 約150MB (Bunランタイム、TypeScriptコード、Web UIアセットを含む)


ネイティブモジュール (@opentui/core、@parcel/watcher) は、ビルドスクリプトが各プラットフォーム向けの 事前ビルド済みバイナリ をダウンロードするため、
CLIビルドではC/C++のソースコードからのコンパイルは発生しない。
このため、CLIのビルドにおいては、デスクトップアプリビルドのようなGCC 10以降の要件はない。

ソースコードのダウンロード

OpenCodeのGithubにアクセスして、ソースコードをダウンロードする。
ダウンロードしたファイルを解凍する。

tar xf opencode-<バージョン>.tar.gz
cd opencode-<バージョン>


ビルド手順

Step 1 : 環境変数の設定

ソースディレクトリがGitリポジトリでない場合 (tarballから展開しただけの場合等) は、packages/script/src/index.ts 内で git branch --show-current が実行されて失敗するため、環境変数を設定する。

 export OPENCODE_VERSION=<バージョン  例 : 1.14.41>
 export OPENCODE_CHANNEL=latest


環境変数 OPENCODE_VERSION に 0.0.0- で始まらない値を指定すると、git コマンドの呼び出しが回避される。
環境変数 OPENCODE_CHANNEL はビルド成果物の --version 表示およびユーザエージェント文字列に使用される。

Step 2 : Bunのlinker設定

デスクトップアプリビルドのセクションと同様に、リポジトリルートの bunfig.toml に linker = "hoisted" を追加する。

vi /path/to/opencode-<バージョン>/bunfig.toml



 [install]
 exact = true
 linker = "hoisted"
 
 [test]
 root = "./do-not-run-tests-from-root"


CLI単体のビルドではViteは使用されないため、isolated linkerでも動作する可能性がある。
ただし、OpenCode Desktopのビルドと環境を共有する場合は、整合性を保つためhoistedモードを推奨する。

Step 3 : 依存パッケージのインストール

リポジトリルートで依存パッケージをインストールする。
このリポジトリはBunワークスペース構成のモノレポであるため、ルートでの bun install 実行で全パッケージの依存関係がインストールされる。

isolated linkerからhoistedに切り替えた直後、または、過去のnode_modulesが残存している場合は、全てのnode_modulesディレクトリを削除してから再インストールする。

cd /path/to/opencode-<バージョン>
rm -rf node_modules packages/*/node_modules packages/*/*/node_modules
bun install


もし、bun installに失敗する場合は、node-gypをインストールする。

bun add node-gyp -D
# または
npm install -g node-gyp


Step 4 : ビルドの実行

ビルドスクリプトを実行する。

./packages/opencode/script/build.ts --single


--single フラグは、現在のプラットフォームのみをビルドする。(例: linux-x64)
フラグなしで実行すると、全12プラットフォーム分のクロスコンパイルを試みる。
(linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64、win32-arm64、各baselineおよびmuslバリアント)

ビルドスクリプトの処理内容を以下に示す。

  1. packages/opencode/script/generate.ts が https://models.dev/api.json からモデルデータを取得して、packages/opencode/src/provider/models.ts 等のスナップショットを生成する。
  2. Web UI (packages/app) を vite build でビルドして、生成されたアセットを単一バイナリに埋め込む。
  3. @opentui/core および @parcel/watcher の全プラットフォーム向けプリビルドバイナリをインストールする。(bun install --os="*" --cpu="*")
  4. Bun.build() の compile オプションでTypeScriptをスタンドアロンバイナリにコンパイルして、packages/opencode/dist/opencode-linux-x64/bin/opencode に出力する。
  5. 自動Smoke testとして、生成されたバイナリの --version を実行して、出力を確認する。


動作確認

ビルドが完了した後、バイナリが生成されたかどうかを確認する。

ls -la packages/opencode/dist/opencode-linux-x64/bin/opencode


バージョンを表示する。

./packages/opencode/dist/opencode-linux-x64/bin/opencode --version


ヘルプを表示する。

./packages/opencode/dist/opencode-linux-x64/bin/opencode --help


TUIを起動する。

./packages/opencode/dist/opencode-linux-x64/bin/opencode



システムへのインストール

ビルドしたバイナリを /usr/local/bin/ にコピーすると、システム全体で opencode コマンドとして使用できる。

sudo cp packages/opencode/dist/opencode-linux-x64/bin/opencode /usr/local/bin/opencode
sudo chmod +x /usr/local/bin/opencode


ユーザディレクトリにのみインストールする場合は、~/.local/bin/ 等にコピーする。

mkdir -p ~/.local/bin
cp packages/opencode/dist/opencode-linux-x64/bin/opencode ~/.local/bin/opencode
chmod +x ~/.local/bin/opencode


トラブルシューティング

トラブルシューティング
問題 原因 対策
git branch --show-current 失敗 ソースがGitリポジトリではない 環境変数を設定する。

export OPENCODE_VERSION=1.14.41
export OPENCODE_CHANNEL=latest
models.dev に接続できない ネットワーク制限またはプロキシ環境 事前に api.json をダウンロードしておき、環境変数 MODELS_DEV_API_JSON=/path/to/api.json で指定する。
詳細は、後述のオフライン環境でのビルドを参照すること。
This script requires bun@^X.X.X, but you are using bun@X.X.X Bunのバージョンが古い Bunをアップグレードする。
bun upgrade
GLIBCバージョン不足 GLIBCバージョンが古い --single に加えて --baseline フラグを追加してビルドする。
または、muslビルドを検討する。
error: File not found ".../packages/sdk/js/node_modules/cross-spawn" isolated linker時代の壊れたシンボリックリンクが残存している 全ての node_modules を削除して、再インストールする。
詳細は、Step 3を参照すること。
Smoke testの失敗 バイナリの実行可能パーミッションがない、またはGLIBCバージョン不足 chmod +x でパーミッションを付与する。
GLIBCの場合は --baseline フラグを試行する。


オフライン環境でのビルド

ネットワークに接続できない場合、モデルデータを事前にダウンロードしておく必要がある。
オンライン環境で事前にダウンロードする。

curl -o api.json https://models.dev/api.json


ビルド時にローカルファイルを指定する。

export MODELS_DEV_API_JSON=/path/to/api.json
./packages/opencode/script/build.ts --single

<br

baselineビルド

CPUがAVX2命令セットをサポートしていない場合、--baseline フラグを追加する。

./packages/opencode/script/build.ts --single --baseline


baselineビルドの出力先は packages/opencode/dist/opencode-linux-x64-baseline/bin/opencode となる。

全プラットフォーム向けクロスコンパイル

--single フラグを外して実行すると、全12プラットフォーム向けのバイナリを生成する。

./packages/opencode/script/build.ts


ただし、Smoke testは現在のプラットフォーム向けのバイナリのみで実行される。
他プラットフォーム向けのバイナリは、対象プラットフォーム上で別途動作確認する必要がある。


デスクトップアプリケーションのビルド

OpenCode Desktopは、Electronベースのデスクトップアプリケーションである。

バージョン 1.14.40以降、Tauri v2からElectronへ移行されており、Rustツールチェーンは不要となっている。

デスクトップアプリケーションの構成

Desktop アプリの構成
項目 内容
フレームワーク Electron 41.x + electron-vite + electron-builder
フロントエンド SolidJS + Vite (TypeScript)
メインプロセス Node.js (TypeScript、packages/desktop/src/main/)
サイドカー OpenCode サーバの Node.js バンドル
packages/opencode/dist/node/ として生成され、utilityProcess.fork でメインプロセスから子プロセスとして起動される。
パッケージング electron-builder
出力形式 (Linux) AppImage、debパッケージ、rpmパッケージ
ソースディレクトリ packages/desktop/src/main/ (Electronメインプロセス)
packages/desktop/src/preload/ (preloadスクリプト)
packages/desktop/src/renderer/ (SolidJSフロントエンド)
設定ファイル packages/desktop/electron.vite.config.ts (electron-vite)
packages/desktop/electron-builder.config.ts (electron-builder)


旧Tauri版とは異なり、独立したCLIバイナリをサイドカーとしてバンドルしない。
代わりに、packages/opencode/src/node.ts から生成されるNode.jsバンドル (packages/opencode/dist/node/) がメインプロセスのutilityProcessとして起動される。
そのため、CLIバイナリのビルドセクションでビルドした opencode バイナリは、デスクトップアプリのビルドには使用されない。

ビルドの前提条件

Bun ランタイム

ビルドにはBun 1.3.13以上が必要である。
ルートの package.json 内 packageManager フィールドで bun@1.3.13 が指定されている。

bun --version



依存ライブラリのインストール

Electron-builderがLinuxパッケージ (rpm / deb / AppImage) を生成するために、以下に示すツールが必要である。

sudo zypper install -t pattern devel_basis
sudo zypper install rpm-build dpkg fakeroot


  • rpm-build
    rpmパッケージの生成に必要
  • dpkg、fakeroot
    debパッケージの生成に必要


electron-builderはAppImageを生成するために必要なツールを内部で自動取得するため、追加のインストールは不要である。

Tauri版とは異なり、Rustツールチェーン (rustc、cargo) およびwebkit2gtk3-develは不要 である。

ソースコードのダウンロード

OpenCodeのGithubにアクセスして、ソースコードをダウンロードする。
ダウンロードしたファイルを解凍する。

tar xf opencode-<バージョン>.tar.gz
cd opencode-<バージョン>


ビルド

Step 1 : 環境変数の設定

ソースディレクトリがGitリポジトリでない場合、ビルド過程で git branch --show-current が実行されて失敗するため、環境変数を設定する。

 export OPENCODE_VERSION=<バージョン  例 : 1.14.41>
 export OPENCODE_CHANNEL=<prod / dev / beta のいずれかを指定>


環境変数 OPENCODE_VERSION に 0.0.0- で始まらない値を指定すると、Git呼び出しが回避される。

環境変数 OPENCODE_CHANNEL は dev、beta、prod のいずれかを指定する。
それ以外の値を指定した場合、packages/desktop/electron-builder.config.ts および packages/desktop/electron.vite.config.ts 内で dev として扱われる。

OPENCODE_CHANNELの値
値 appId productName RPMパッケージ名
dev ai.opencode.desktop.dev OpenCode Dev opencode-dev
beta ai.opencode.desktop.beta OpenCode Beta opencode-beta
prod ai.opencode.desktop OpenCode opencode


Step 2 : Bunのlinker設定

Bun 1.3のデフォルトのisolated linkerでは、各パッケージの依存関係が node_modules/.bun/ 配下に隔離されたシンボリックリンク構造で配置される。
この構造では、Vite (electron-viteのレンダラビルド) のCommonJSリゾルバが、ワークスペース外の shiki 等のtransitive依存を解決できず、以下に示すエラーが発生する。

[commonjs--resolver] Failed to resolve entry for package "shiki".
The package may have incorrect main/module/exports specified in its package.json.


このエラーを回避するため、リポジトリルートの bunfig.toml を編集して、linkerをhoistedモード (npm互換のフラットなnode_modules構造) に切り替える。

vi /path/to/opencode-<バージョン>/bunfig.toml


bunfig.toml ファイルの [install] セクションに linker = "hoisted" を追加する。

 [install]
 exact = true
 linker = "hoisted"
 
 [test]
 root = "./do-not-run-tests-from-root"


Step 3 : 依存パッケージのインストール

プロジェクトルートで依存パッケージをインストールする。
このリポジトリはBunワークスペース構成のモノレポであり、ルートで bun install を実行することで全パッケージの依存関係がインストールされる。

すでに過去にisolated linkerで bun install を実行している場合、各パッケージの node_modules 配下に古いシンボリックリンクが残っている。
hoistedモードで再構築する前に、すべての node_modules ディレクトリを削除する。

cd /path/to/opencode-<バージョン>
rm -rf node_modules packages/*/node_modules packages/*/*/node_modules


削除しないまま bun install を実行した場合、isolated時代の壊れたシンボリックリンクが残存し、ビルド時に以下に示すエラーが発生する。

error: File not found "/path/to/opencode-<バージョン>/packages/sdk/js/node_modules/cross-spawn"


クリーンアップ後、依存パッケージをインストールする。

bun install


postinstall フックで fix-node-pty が自動実行される。

もし、bun installに失敗する場合は、node-gypをインストールする。

bun add node-gyp -D
# または
npm install -g node-gyp


Step 4 : Electronビルドの実行

Electronメインプロセス、preload、レンダラのビルドを実行する。

bun run --cwd packages/desktop build


build スクリプト実行時、以下の処理が prebuild フックで自動実行される。

  • packages/desktop/scripts/copy-icons.ts でチャンネル別のアイコンを resources/icons/ にコピーする。
  • packages/opencode/script/build-node.ts でNode.jsサイドカーバンドルを packages/opencode/dist/node/ に出力する。


その後、electron-vite build がメインプロセス (out/main/)、preload (out/preload/)、レンダラ (out/renderer/) の3つのバンドルを生成する。

ネットワーク接続が必要である。

  • packages/opencode/script/generate.ts が https://models.dev/api.json からモデル定義を取得する。
  • SentryのPlugin等が外部リソースにアクセスする場合がある。


Step 5 : Linuxパッケージの生成

electron-builderでAppImage、debパッケージ、rpmパッケージを生成する。

electron-builderは、@electron/rebuild を内部で実行して、ネイティブモジュール (msgpackr-extract 等) を Electron向けに再コンパイルする。
msgpackr-extract のビルドには -std=gnu++20 オプションが指定されるため、C++20をサポートするGCC 10以降が必要である。

※注意
GCC 9以前では、以下に示すエラーが発生してビルドが失敗する。

g++: error: unrecognized command line option '-std=gnu++20'; did you mean '-std=gnu++03'?
make: *** [extract.target.mk:142: Release/obj.target/extract/src/extract.o] エラー 1

⨯ node-gyp failed to rebuild '/path/to/opencode-<バージョン>/node_modules/msgpackr-extract'


electron-builderを実行する。

bun run --cwd packages/desktop package:linux


このコマンドは、electron-builder --linux --config electron-builder.config.ts を実行する。
packages/desktop/electron-builder.config.ts 内の linux.target に AppImage、deb、rpmが指定されている。

特定の形式のみ生成する場合は、--linux の後に形式を指定する。

# rpmのみ
bun run --cwd packages/desktop package:linux -- rpm

# debのみ
bun run --cwd packages/desktop package:linux -- deb

# AppImageのみ
bun run --cwd packages/desktop package:linux -- AppImage


生成されたファイルの確認

出力先は packages/desktop/dist/ である。
ファイル名のフォーマットは packages/desktop/electron-builder.config.ts 内の artifactName で指定される。
(デフォルト: opencode-desktop-${os}-${arch}.${ext})

# rpmパッケージ
ls -la packages/desktop/dist/*.rpm

# debパッケージ
ls -la packages/desktop/dist/*.deb

# AppImage
ls -la packages/desktop/dist/*.AppImage


動作確認

rpmパッケージをインストールして起動を確認する。

# rpmパッケージをインストール
sudo zypper install ./packages/desktop/dist/opencode-desktop-linux-x64.rpm

# OpenCodeデスクトップアプリを起動
# OPENCODE_CHANNEL=devでビルドした場合
opencode-dev


debパッケージで動作確認する場合は、以下に示すコマンドを実行する。

sudo dpkg -i ./packages/desktop/dist/opencode-desktop-linux-x64.deb


AppImageの場合、ダウンロードしたファイルに実行権限を付与してそのまま起動する。

chmod +x ./packages/desktop/dist/opencode-desktop-linux-x64.AppImage
./packages/desktop/dist/opencode-desktop-linux-x64.AppImage


トラブルシューティング

トラブルシューティング
問題 原因 対策
git branch --show-current 失敗 ソースがGitリポジトリではない 環境変数を設定する。

export OPENCODE_VERSION=1.14.41
export OPENCODE_CHANNEL=dev
[commonjs--resolver] Failed to resolve entry for package "shiki" Bunのisolated linkerが原因で、ワークスペース外の transitive 依存をViteが解決できない bunfig.toml ファイルの [install] セクションに linker = "hoisted" を設定して、bun install を再実行する。
詳細は、Step 2を参照すること。
error: File not found ".../packages/sdk/js/node_modules/cross-spawn" isolated linkerで作成された壊れたシンボリックリンクが残存している 全ての node_modules を削除して、再インストールする。

rm -rf node_modules \
   packages/*/node_modules \
   packages/*/*/node_modules
bun install
models.dev に接続できない ネットワーク制限 事前に api.json をダウンロードしておき、MODELS_DEV_API_JSON=/path/to/api.json を環境変数で指定する。
rpmパッケージが生成されない rpm-buildツール不足 sudo zypper install rpm-build でrpmビルドツールをインストールする。
debパッケージが生成されない dpkg / fakeroot不足 sudo zypper install dpkg fakeroot でdebビルドツールをインストールする。
Wayland環境で画面が真っ白になる ElectronのデフォルトがX11プロトコル 起動時に --ozone-platform=wayland または --ozone-platform-hint=auto フラグを付与する。
例 : opencode-dev --ozone-platform-hint=auto
node-ptyのビルド失敗 ネイティブモジュールのコンパイル環境不足 ビルドツールをインストールする。
sudo zypper install gcc gcc-c++ make python3
Electronのダウンロード失敗 ネットワーク制限またはプロキシ環境 プロキシ環境では HTTPS_PROXY 環境変数を設定する。
または ELECTRON_MIRROR 環境変数でミラーURLを指定する。


デバッグビルド

問題の調査が必要な場合、開発モードで起動できる。

bun run --cwd packages/desktop dev


このコマンドは electron-vite dev を実行し、HMR (Hot Module Replacement) 対応の開発サーバを起動する。
DevToolsが自動的に有効になり、レンダラプロセスを [Ctrl] + [Shift] + [I] で検証できる。


Oh my OpenAgents (Oh my OpenCode)

Oh my OpenAgentsは、OpenCode用のマルチエージェントオーケストレーションプラグインである。
フック、MCPサーバ、スキル、専門エージェントを活用してOpenCodeの機能を拡張する。


主な機能

Oh my OpenAgentsは以下に示す機能を提供する。

Oh my OpenAgents 機能一覧
機能 説明
ultrawork 複雑なタスクを専門エージェントに自動分割して並列処理するマジックワード
フック統合 ツール実行前後に自動実行されるフック (コード品質チェック、テスト自動実行等)
MCP統合 Context7 (ライブラリドキュメント取得)、Sequential Thinking (構造的推論)
LSP/AST解析 Language Server ProtocolとAST解析による高精度なコード理解
スキルシステム 再利用可能なプロンプトテンプレート
例: /ultra


専門エージェント

Oh my OpenAgentsは以下の専門エージェントを提供する。

専門エージェント一覧
エージェント名 役割
Sisyphus プランニングと実装を担当するメインエージェント
タスク分割、実装、テスト、反復改善を行う。
Oracle コードベース全体の調査・分析を担当
プロジェクト構造の把握、依存関係の追跡を行う。
Frontend Engineer フロントエンド開発を担当
React / Next.js等のUI実装、アクセシビリティ対応を行う。
Librarian ドキュメント管理を担当
README、API仕様書、変更履歴の作成・更新を行う。
Explorer 未知のコードベースの探索を担当
新しいプロジェクトの構造理解や技術スタックの調査を行う。


インストール

インストールの前提条件は以下の通りである。

  • OpenCode v1.0.150以上
  • Node.js または Bun


Oh my OpenAgentsをインストールする。

bunx oh-my-opencode@latest
# または
npx oh-my-opencode@latest


非対話モードでインストールする場合は以下のコマンドを実行する。

bunx oh-my-opencode@latest --non-interactive


設定

設定ファイルは以下の場所に配置する。

  • プロジェクト単位
    .opencode/oh-my-opencode.json
  • グローバル
    ~/.config/opencode/oh-my-opencode.json


設定ファイルはJSONC (コメント付きJSON) 形式で記述する。
以下に設定ファイルの例を示す。

 {
    "mcpServers": {
       "context7": true,
       "thinking": true
    },
    "agents": {
       "sisyphus": true,
       "oracle": true,
       "frontend": true,
       "librarian": true,
       "explorer": true
    },
    "hooks": {
       "afterEdit": true,
       "afterWrite": true
    },
    "skills": {
       "ultra": true
    }
 }


下表に、各設定項目の説明を示す。

設定項目一覧
カテゴリ 設定項目 説明
mcpServers - MCPサーバの有効 / 無効を設定する。
context7 ライブラリドキュメント取得サーバ
thinking 構造的推論サーバ
agents - 専門エージェントの有効/無効を設定する。
sisyphus 個別に制御可能
oracle 個別に制御可能
frontend 個別に制御可能
librarian 個別に制御可能
explorer 個別に制御可能
hooks - フックの有効 / 無効を設定する。
afterEdit ファイル編集後に自動チェックを実行する。
afterWrite ファイル作成後に自動チェックを実行する。
skills - スキルの有効 / 無効を設定する。
ultra ultraworkスキルを有効化する。


使用方法

プロンプトに ultrawork というキーワードを含めるだけで、複雑なタスクを専門エージェントに自動分割して並列処理する。

使用例を以下に示す。

  • 大規模リファクタリング 
    ultrawork このプロジェクトの認証システムをリファクタリングして
  • 新機能実装 
    ultrawork ユーザ管理機能を実装して
  • ドキュメント調査 
    ultrawork このコードベースを分析してドキュメントを作成して


アンインストール

プロジェクト単位の設定ファイルを削除する。

rm -rf .opencode/agents   \
       .opencode/hooks    \
       .opencode/skills   \
       .opencode/mcp.json \
       .opencode/oh-my-opencode.json


グローバル設定を削除する。

rm -rf ~/.config/opencode/oh-my-opencode.json


注意事項

Oh my OpenAgentsを使用する際は以下の点に注意すること。

  • AnthropicモデルのOpenCode対応はコミュニティ主導の取り組みであり、Anthropicの公式サポート対象外である。
  • フック機能により外部コマンドが自動実行されるため、設定内容を事前に確認すること。
  • MCPサーバはネットワークアクセスを行う場合があるため、セキュリティポリシーに準じて使用すること。



注意事項

プライバシーとデータ取り扱い

OpenCodeはオープンソースであり、コードの透明性を確保している。

  • ローカルでの処理を優先、コードの送信は最小限に抑制する。
  • 使用するAIプロバイダのプライバシーポリシーを確認すること。
  • GitHubリポジトリで実装を検証可能



生成コードの検証

AIが生成したコードは必ずレビューして検証する。

  • コードの動作を確認
  • セキュリティ上の問題がないか確認
  • ライセンス上の問題がないか確認
  • コーディング規約に準拠しているか確認



セキュリティ

APIキーやパスワード等の機密情報をコードに含めないように注意する。

  • APIキー、パスワード等の機密情報をコードに含めない。
  • 環境変数や設定ファイルで管理する。
  • .gitignore ファイルで機密情報を含むファイルを除外する。



「https://mochiu.net/index.php?title=インストール_-_OpenCode&oldid=14711」から取得