「OpenCodeの設定 - プラグイン」の版間の差分

提供: MochiuWiki : SUSE, EC, PCB

ページの作成:「== 概要 == OpenCodeのプラグインシステムは、TypeScript / JavaScriptで記述したソースコードをOpenCodeの動作に組み込み、独自の機能拡張を実現する仕組みである。<br> <br> プラグインはフック (hook) ベースのイベント駆動型アーキテクチャを採用しており、<br> セッションの開始・終了、ファイル操作、ツール実行、シェルコマンドの実行といった各種イベン…」
 
編集の要約なし
665行目: 665行目:
*: <code>tool.execute.before</code> で例外をスローした場合、ツールの実行が中断される。
*: <code>tool.execute.before</code> で例外をスローした場合、ツールの実行が中断される。
*: 意図しない <code>throw</code> がないか確認する。
*: 意図しない <code>throw</code> がないか確認する。
<br><br>
<br><br>
== プラグインマーケットプレイス ==
OpenCodeはプラグインマーケットプレイス機能を提供しており、コミュニティが提供するプラグインを簡単にインストールできる。<br>
<br>
==== マーケットプレイスからのプラグイン追加 ====
マーケットプレイスからプラグインを追加するには、以下のコマンドを使用する。<br>
<br>
<syntaxhighlight lang="sh">
# マーケットプレイスにプラグインを追加
/plugin marketplace add <マーケットプレイス名>/<プラグイン名>
# 例: Microsoft Docs MCPを追加
/plugin marketplace add microsoftdocs/mcp
</syntaxhighlight>
<br>
==== プラグインのインストール ====
追加したマーケットプレイスからプラグインをインストールするには、以下のコマンドを使用する。<br>
<br>
<syntaxhighlight lang="sh">
# プラグインをインストール
/plugin install <plugin-name>@<marketplace-name>
# 例: Microsoft Docsプラグインをインストール
/plugin install microsoft-docs@microsoft-docs-marketplace
</syntaxhighlight>
<br>
==== Microsoft Docs MCPの設定例 ====
Microsoft Docs MCPを使用すると、OpenCodeからMicrosoftおよびAzureの公式ドキュメントにアクセスできる。<br>
公式ドキュメントを検索し、コードサンプルを取得し、詳細な技術情報を参照できる。<br>
<br>
<syntaxhighlight lang="sh">
# Microsoft Docs MCPをマーケットプレイスに追加
/plugin marketplace add microsoftdocs/mcp
# Microsoft Docs プラグインをインストール
/plugin install microsoft-docs@microsoft-docs-marketplace
</syntaxhighlight>
<br><br>
== よく使用されるプラグイン ==
OpenCodeのエコシステムには多くのコミュニティプラグインが存在する。<br>
<br>
使用される頻度の高い便利なプラグインをカテゴリ別に示す。<br>
<br>
==== 認証関連プラグイン ====
認証関連のプラグインを使用すると、APIクレジットの代わりに既存のサブスクリプションを使用できる。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明
|-
| opencode-openai-codex-auth || ChatGPT Plus/Proのサブスクリプションを使用してOpenAI Codexバックエンドを利用する。<br>OAuth認証をサポートする。
|-
| opencode-gemini-auth || 既存のGeminiプランを使用してGoogleアカウントで認証する。<br>API課金の代わりにGeminiプランを使用できる。
|-
| opencode-antigravity-auth || Antigravityの無料モデルを使用してAPI課金なしでモデルを利用する。<br>GeminiおよびAnthropicモデルに対応する。
|-
| opencode-google-antigravity-auth || Google Antigravity OAuthを使用する拡張版。<br>Google検索サポートと堅牢なAPI処理を提供する。
|}
</center>
<br>
==== 開発環境プラグイン ====
開発環境を拡張するプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明
|-
| opencode-daytona || Daytonaサンドボックス内でOpenCodeセッションを自動実行する。<br>Git同期とライブプレビュー機能を提供する。
|-
| opencode-devcontainers || 複数ブランチのdevcontainer分離を実現する。<br>シャロークローンと自動割り当てポートをサポートする。
|-
| opencode-morph-fast-apply || Morph Fast Apply APIを使用した高速なコード編集を実現する。<br>10,500+ tokens/secの編集速度と遅延編集マーカーを提供する。
|-
| opencode-type-inject || ファイル読み込み時にTypeScript/Svelteの型を自動注入する。<br>型参照ツールを提供する。
|}
</center>
<br>
==== エージェント・オーケストレーションプラグイン ====
AIエージェントの動作を拡張・調整するプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明
|-
| opencode-background-agents || Claude Codeスタイルのバックグラウンドエージェントを提供する。<br>非同期委任とコンテキスト永続化をサポートする。
|-
| oh-my-opencode || バックグラウンドエージェント、LSP/AST/MCPツール、厳選されたエージェントを提供する。<br>詳細は専用ページを参照のこと。
|-
| micode || 構造化されたブレインストーム→計画→実装のワークフローを提供する。<br>セッション継続性とサブエージェントオーケストレーションをサポートする。
|-
| opencode-workspace || バンドルされたマルチエージェントオーケストレーションハーネスを提供する。<br>16コンポーネントを1つのインストールで利用できる。
|}
</center>
<br>
==== 通知・モニタリングプラグイン ====
セッション状態の通知や使用状況の追跡を行うプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明
|-
| opencode-notify || タスク完了時のネイティブOS通知を提供する。<br>バックグラウンドタスクの完了を通知する。
|-
| opencode-notificator || デスクトップ通知とサウンドアラートを提供する。<br>OpenCodeセッションの状態変化を通知する。
|-
| opencode-notifier || 権限、完了、エラーイベントのデスクトップ通知とサウンドアラートを提供する。
|-
| opencode-wakatime || Wakatimeを使用してOpenCodeの使用状況を追跡する。<br>コーディング時間の自動記録を行う。
|-
| opencode-quota || プロバイダー間のクォータとトークン使用量を追跡する。<br>自動トースト通知とスラッシュコマンドを提供する。
|}
</center>
<br>
==== その他のユーティリティプラグイン ====
その他の便利なプラグインである。<br>
<br>
<center>
{| class="wikitable"
! プラグイン名 !! 説明
|-
| opencode-helicone-session || リクエストグループ化のためのHeliconeセッションヘッダーを自動注入する。<br>API使用状況の分析に使用する。
|-
| opencode-dynamic-context-pruning || トークン使用量を最適化する。<br>古いツール出力をコンテキストから削除する。
|-
| opencode-supermemory || Supermemoryを使用してセッション間の永続メモリを提供する。<br>長期的なコンテキスト保持を実現する。
|-
| opencode-agent-memory || Lettaエージェントにインスパイアされた永続的な自己編集可能メモリブロックを提供する。<br>エージェントの記憶を保持する。
|-
| opencode-direnv || セッション開始時にdirenv環境変数を自動的に読み込む。<br>Nix flakesとの相性が良い。
|-
| opencode-scheduler || launchd (Mac) または systemd (Linux) を使用して定期的なジョブをスケジュールする。<br>cron構文をサポートする。
|-
| opencode-websearch-cited || 対応プロバイダーのネイティブウェブ検索サポートを追加する。<br>Google groundedスタイルの引用付き検索を提供する。
|-
| opencode-md-table-formatter || LLMが生成したMarkdownテーブルを整形する。<br>テーブルの可読性を向上させる。
|-
| opencode-shell-strategy || 非対話型シェルコマンドの指示を提供する。<br>TTY依存操作によるハングを防止する。
|}
</center>
<br>
==== プラグインのインストール方法 ====
プラグインをインストールするには、<u>opencode.jsonファイル</u> の <code>plugin</code> フィールドにパッケージ名を指定する。<br>
<br>
<syntaxhighlight lang="json">
{
    "$schema": "https://opencode.ai/config.json",
    "plugin": [
      "opencode-wakatime",
      "opencode-notify",
      "@sveltejs/opencode"
    ]
}
</syntaxhighlight>
<br>
スコープ付きnpmパッケージ (例: <u>@sveltejs/opencode</u>) もサポートされている。<br>
<br>
==== 公式エコシステムリソース ====
OpenCodeのエコシステムに関する情報は、以下のリソースから入手できる。<br>
<br>
* [https://opencode.ai/docs/ecosystem/ OpenCodeの公式エコシステムページ]
*: 公式にリストされたプラグインとプロジェクトを確認できる。
*: <br>
* [https://github.com/awesome-opencode/awesome-opencode awesome-opencode GitHubリポジトリ]
*: コミュニティによって管理される厳選リスト
*: プラグイン、テーマ、エージェント、リソースが含まれる。
*: <br>
* [https://opencode.cafe opencode.cafe]
*: コミュニティ駆動のマーケットプレイス
*: 拡張機能、プラグイン、ツールを閲覧・共有できる。
<br><br>
<br><br>



2026年2月27日 (金) 06:06時点における版

概要

OpenCodeのプラグインシステムは、TypeScript / JavaScriptで記述したソースコードをOpenCodeの動作に組み込み、独自の機能拡張を実現する仕組みである。

プラグインはフック (hook) ベースのイベント駆動型アーキテクチャを採用しており、
セッションの開始・終了、ファイル操作、ツール実行、シェルコマンドの実行といった各種イベントに対して処理を追加できる。

プラグインが提供する主な機能は以下の通りである。

  • セッション管理の拡張
    セッションの作成・削除・アイドル状態等のイベントに反応して処理を追加する。
  • ツール実行の制御
    ツール実行前後に検証・変換・ログ記録等の処理を挿入する。
  • 環境変数の注入
    シェル実行時にプロジェクト固有の環境変数を動的に追加する。
  • カスタムツールの定義
    LLMが呼び出せる独自のツールを作成し、OpenCodeの機能を拡張する。


プラグインはプロジェクト固有 または グローバルに配置でき、OpenCode起動時に自動的に読み込まれる。


プラグインの基本構造

プラグインは非同期関数として実装されており、コンテキストオブジェクトを引数として受け取り、フックオブジェクトを返す構造を持つ。

基本的なプラグインの構造を以下に示す。

 import { Plugin } from "opencode/plugin"
 
 export const MyPlugin: Plugin = async ({ client, project, $, directory }) => {
    // 初期化処理をここに記述する
 
    return {
       "session.created": async ({ session }) => {
          // セッション作成時の処理
       },
       "tool.execute.before": async ({ tool, args }) => {
          // ツール実行前の処理
       }
    }
 }


コンテキストはデストラクチャリングで受け取ることが重要である。

  • 正しい記述方法
    async ({ client, project, $ }) => { ... }
  • 誤った記述方法
    async (client, project, $) => { ... }


コンテキストオブジェクト

コンテキストオブジェクトには、プラグイン内で利用できる各種情報とAPIが含まれる。

プロパティ 説明
client OpenCode SDKクライアント
ログ出力やAPI呼び出しに使用する。
例: client.app.log("info", "メッセージ")
project プロジェクト情報
現在のプロジェクトのメタデータにアクセスできる。
$ シェルコマンド実行用のAPI (BunのShell API)
プラグイン内からシェルコマンドを実行する時に使用する。
directory 現在の作業ディレクトリのパス
worktree ワークツリー情報
Gitのワークツリーに関する情報にアクセスできる。
app アプリケーション参照
OpenCodeアプリケーション全体への参照を提供する。


フックオブジェクト

フックオブジェクトは、プラグインが対応する各イベントとその処理関数をマッピングしたオブジェクトである。

フックオブジェクトの基本的な構造を以下に示す。

 return {
    // イベント名: 処理関数
    "session.created": async ({ session }) => { ... },
    "tool.execute.before": async ({ tool, args }) => { ... },
    "shell.env": async ({ env }) => { ... }
 }


フックの処理関数は非同期関数として定義して、イベントに応じたパラメータを受け取る。

一部のフックでは、受け取ったパラメータを変更して返すことにより、OpenCodeの動作を変更できる。


ディレクトリ構造

プラグインは以下の2つの場所に配置できる。

  • プロジェクト固有のプラグイン
    .opencode/plugins/
    特定のプロジェクトにのみ適用される。
  • グローバルプラグイン
    ~/.config/opencode/plugins/
    全てのプロジェクトで使用できる。


OpenCode起動時に上記のディレクトリが自動的にスキャンされ、プラグインが読み込まれる。

npmパッケージとして配布されているプラグインは、opencode.jsonファイルplugins フィールドに指定することで使用できる。

 {
    "plugins": [
       "opencode-plugin-example",
       "./local-plugin"
    ]
 }


プロジェクトにプラグインを追加する場合の推奨ディレクトリ構成を以下に示す。

 # 例: QML/C++プロジェクト

 .opencode/
 ├── plugins/
    ├── build-notify.ts       # CMakeビルド結果通知プラグイン
    ├── qml-hot-reload.ts     # QMLホットリロード検知プラグイン
    └── env-protection.ts     # 環境変数保護プラグイン
 └── package.json              # 依存関係の定義



プラグインの作成方法

基本的なプラグイン

最もシンプルなプラグインの例を以下に示す。

以下に示すプラグインは、セッション作成時にログを出力するだけの基本的な実装である。

  • ファイルの配置場所の例
    .opencode/plugins/hello.ts


 import { Plugin } from "opencode/plugin"
 
 export const HelloPlugin: Plugin = async ({ client }) => {
    client.app.log("info", "HelloPlugin: 読み込み完了")
 
    return {
       "session.created": async ({ session }) => {
          client.app.log("info", `新しいセッションが作成されました: ${session.id}`)
       },
       "session.deleted": async ({ session }) => {
          client.app.log("info", `セッションが削除されました: ${session.id}`)
       }
    }
 }


TypeScript / JavaScriptモジュール

OpenCodeのプラグインは、TypeScript または JavaScriptで記述できる。
TypeScriptを使用すると、型チェックによる安全性が向上するため推奨される。

TypeScriptプラグインの例を以下に示す。

 import { Plugin, tool } from "opencode/plugin"
 import { z } from "zod"
 
 export const FullExamplePlugin: Plugin = async ({ client, directory }) => {
    // 初期化処理
    const startTime = Date.now()
    client.app.log("info", "プラグイン初期化中...")
 
    return {
       "session.created": async ({ session }) => {
          client.app.log("info", `セッション開始: ${session.id}`)
       },
 
       "session.idle": async ({ session }) => {
          const elapsed = Date.now() - startTime
          client.app.log("info", `セッションがアイドル状態になりました (経過時間: ${elapsed}ms)`)
       },
 
       "session.deleted": async ({ session }) => {
          // 状態のクリーンアップ
          client.app.log("info", `セッション終了: ${session.id}`)
       },
 
       "tool.execute.before": async ({ tool, args }) => {
          client.app.log("debug", `ツール実行前: ${tool.name}`)
       }
    }
 }



利用可能なフック

セッションフック

セッションのライフサイクルに関連するフックである。

セッションフック一覧
フック名 説明 用途
session.created セッションが新規作成された時 初期化処理、ログ記録
session.updated セッション情報が更新された時 状態の同期
session.idle セッションがアイドル状態になった時 通知送信、リソース解放
session.deleted セッションが削除された時 クリーンアップ処理 (重要)
session.status セッションのステータスが変化した時 ステータス監視
session.compacted セッションがコンパクションされた時 コンパクション後の処理


session.deleted フックでの状態クリーンアップは、メモリリーク防止のために特に重要である。

ファイルフック

メッセージとメッセージパーツに関連するフックである。

ファイルフック一覧
フック名 説明
message.updated メッセージが更新された時
message.removed メッセージが削除された時
message.part.updated メッセージパーツが更新された時
message.part.removed メッセージパーツが削除された時


ツールフック

ツールの実行に関連するフックである。
ツールフックを使用すると、ツール実行前後に処理を追加したり、実行を制御したりできる。

ツールフック一覧
フック 説明
tool.execute.before ツール実行前に呼び出される。
入力値の検証や変更が可能である。
throw でツール実行を中断できる。
tool.execute.after ツール実行後に呼び出される。
ツールの出力結果に対して後処理を行える。


ツールフックの使用例を以下に示す。

 "tool.execute.before": async ({ tool, args }) => {
    // 特定のツールの実行前に検証を行う
    if (tool.name === "bash" && args.command.includes("rm -rf")) {
       throw new Error("危険なコマンドの実行を拒否しました")
    }
 },
 
 "tool.execute.after": async ({ tool, args, result }) => {
    // ツール実行後にログを記録する
    client.app.log("info", `ツール実行完了: ${tool.name}`)
 }


コマンドフック

LLMへのリクエストに関連するフックである。

LLMリクエスト関連フック
フック 説明
chat.params LLMに送信するパラメータを変更できる。温度設定やシステムプロンプトの動的変更に使用する。
chat.message LLMから受信したメッセージに対応する処理を行う。


シェルフック

シェルコマンドの実行に関連するフックである。

LLMリクエスト関連フック
フック 説明
chat.params LLMに送信するパラメータを変更できる。
temperature設定やシステムプロンプトの動的変更に使用する。
chat.message LLMから受信したメッセージに対応する処理を行う。


shell.env フックの使用例を以下に示す。

 "shell.env": async ({ env }) => {
    return {
       ...env,
       MY_PROJECT_API_URL: "https://api.example.com",
       MY_PROJECT_ENV: "development"
    }
 }


LSPフック

Language Server Protocol に関連するフックである。

LSP関連フック
フック 説明
lsp.diagnostics LSPの診断情報 (エラーや警告) が更新された時に呼び出される。
コード品質の監視や自動修正処理に使用する。


下表に、その他の主要なフックを示す。

その他の主要なフック
フック 説明
permission.ask 権限確認ダイアログが表示される前に呼び出される。
permission.replied 権限確認に対してユーザが返答した後に呼び出される。
auth カスタム認証プロバイダを実装する時に使用する。



カスタムツールの作成

プラグインでは tool() ヘルパー関数を使用してカスタムツールを定義できる。

カスタムツールを定義すると、LLMがそのツールを呼び出してタスクを実行できるようになる。

ツールの基本構造

カスタムツールの基本構造を以下に示す。

 import { Plugin, tool } from "opencode/plugin"
 
 export const CustomToolPlugin: Plugin = async ({ client }) => {
    const myTool = tool({
       name: "my_custom_tool",
       description: "このツールの説明。LLMがいつ使用するかを判断するために使用される。",
       parameters: {
          input: tool.schema.string().describe("処理する入力テキスト"),
          count: tool.schema.number().describe("繰り返し回数")
       },
       execute: async (args, context) => {
          // ツールの処理を実装する
          const result = args.input.repeat(args.count)
          return { output: result }
       }
    })
 
    return {
       tools: [myTool]
    }
 }


引数スキーマ (Zod)

カスタムツールの引数スキーマはZodベースのヘルパーを使用して定義する。

利用可能なスキーマ型を以下に示す。

引数スキーマ型一覧
スキーマ型 説明 使用例
tool.schema.string() 文字列型 ファイルパス、テキスト入力
tool.schema.number() 数値型 カウント、タイムアウト値
tool.schema.boolean() 真偽値型 フラグ、スイッチ
tool.schema.enum([...]) 列挙型 選択肢から1つを選ぶ引数
tool.schema.optional(...) 省略可能な型 必須でない引数をラップする


各スキーマ型に .describe() を連結することで、LLMへの説明を追加できる。
説明は詳細に記述するほど、LLMがツールを正しく使用しやすくなる。

 parameters: {
    path: tool.schema.string().describe("操作対象のファイルパス (絶対パスで指定)"),
    mode: tool.schema.enum(["read", "write", "append"]).describe("ファイル操作のモード"),
    encoding: tool.schema.optional(tool.schema.string()).describe("文字エンコーディング (省略時はUTF-8)")
 }


複数ツールのエクスポート

1つのプラグインから複数のカスタムツールをエクスポートするには、tools フィールドに配列で指定する。

 return {
    tools: [toolA, toolB, toolC]
 }


コンテキストアクセス

execute 関数の第2引数 context から、実行時の情報にアクセスできる。

コンテキストプロパティ一覧
プロパティ 説明
context.sessionID 現在のセッションID
context.messageID 現在のメッセージID
context.directory 現在の作業ディレクトリ
context.worktree ワークツリー情報
context.agent 実行中のエージェント情報
context.signal キャンセル用のAbortSignal


context.signal を使用することにより、長時間処理の途中でキャンセルに対応できる。


プラグインの実用例

環境変数保護

機密ファイル (環境変数ファイル、認証情報ファイル等) へのアクセスを禁止するプラグインの実装例を以下に示す。

  • ファイルの配置場所の例
    .opencode/plugins/env-protection.ts


 import { Plugin } from "opencode/plugin"
 
 export const EnvProtection: Plugin = async ({ client }) => {
    const sensitivePatterns = [/\.env/, /credentials/, /\.secret/]

    return {
       "tool.execute.before": async ({ tool, args }) => {
          if (tool.name === "read" && sensitivePatterns.some(p => p.test(args.path))) {
             throw new Error("Access denied to sensitive files")
          }
       }
    }
 }


このプラグインは、read ツールが機密ファイルにアクセスしようとした時に例外をスローして処理を中断する。

セッション通知

セッションがアイドル状態になった時にログを出力するプラグインの実装例を以下に示す。
この例を応用することで、外部の通知サービスへの連携も実現できる。

  • ファイルの配置場所の例
    .opencode/plugins/notification.ts


 import { Plugin } from "opencode/plugin"
 
 export const NotificationPlugin: Plugin = async ({ client }) => {
    return {
       "session.idle": async ({ session }) => {
          client.app.log("info", "Session completed")
          // ここに外部通知サービスへのAPI呼び出し等を追加できる
       }
    }
 }


カスタムツール定義

プロジェクト固有のカスタムツールを定義するプラグインの実装例を以下に示す。
この例では、指定したファイルのメタデータ (行数、サイズ等) を取得するツールを定義している。

  • ファイルの配置場所の例
    .opencode/plugins/custom-tools.ts


 import { Plugin, tool } from "opencode/plugin"
 import { stat, readFile } from "fs/promises"
 
 export const CustomToolsPlugin: Plugin = async ({ client }) => {
    const fileInfoTool = tool({
       name: "get_file_info",
       description: "指定したファイルのメタデータ (行数、ファイルサイズ等) を取得する",
       parameters: {
          path: tool.schema.string().describe("情報を取得するファイルのパス")
       },
       execute: async (args, context) => {
          const stats = await stat(args.path)
          const content = await readFile(args.path, "utf-8")
          const lines = content.split("\n").length

          return {
             size: stats.size,
             lines: lines,
             modified: stats.mtime.toISOString()
          }
       }
    })
 
    return {
       tools: [fileInfoTool]
    }
 }



依存関係の管理

プラグインで外部npmパッケージを使用する場合は、.opencode/package.jsonファイル に依存関係を定義する。

 {
    "name": "opencode-plugins",
    "version": "1.0.0",
    "dependencies": {
       "axios": "^1.6.0",
       "zod": "^3.22.0"
    },
    "devDependencies": {
       "typescript": "^5.3.0",
       "@types/node": "^20.0.0"
    }
 }


OpenCodeの起動時に bun install コマンドが自動的に実行されるため、手動でインストールコマンドを実行する必要はない。

依存関係の管理に関する注意事項を以下に示す。

  • package.jsonファイル は、必ず .opencode/ディレクトリ に配置する。
    プロジェクトルートの package.jsonファイル とは別ファイルである。

  • Bunが使用されるため、npm、yarn、pnpmとは異なる場合がある。
    Bunに対応したパッケージを使用することを確認する。
  • TypeScriptを使用する場合は、型定義パッケージ (@types/*) も依存関係に含める。



推奨される事柄

エラーハンドリング

プラグインのフック内では、適切なエラーハンドリングを実装する。

エラーが発生した場合でも、OpenCodeの動作が停止しないように注意する。

 "session.created": async ({ session }) => {
    try {
       await initializeSession(session.id)
    }
    catch (error) {
       client.app.log("error", `セッション初期化エラー: ${error}`)
       // エラーを再スローしないことで、OpenCodeの動作を継続させる
    }
 }


セッション削除時のクリーンアップ

セッションごとに状態を保持する場合は、session.deleted フックで必ずクリーンアップを行う。
クリーンアップを怠るとメモリリークの原因となる。

 export const StatefulPlugin: Plugin = async ({ client }) => {
    const sessionState = new Map<string, any>()
 
    return {
       "session.created": async ({ session }) => {
          sessionState.set(session.id, { startTime: Date.now() })
       },
       "session.deleted": async ({ session }) => {
          // 必ずクリーンアップする
          sessionState.delete(session.id)
       }
    }
 }


ログ出力

プラグイン内のログ出力は console.log() ではなく、client.app.log() を使用する。
client.app.log() を使用することにより、OpenCodeのログシステムと統合されて適切に管理される。

 // 正しい方法
 client.app.log("info", "処理完了")
 client.app.log("error", "エラーが発生しました")
 client.app.log("debug", "デバッグ情報")
 
 // 避けるべき方法
 console.log("処理完了")


その他のベストプラクティス

  • TypeScriptを使用して型安全性を確保する。
    TypeScriptの型チェックにより、ランタイムエラーを事前に防止できる。

  • 公式フックのみを使用する。
    非公式・内部フックは将来のバージョンで変更される可能性がある。

  • 大規模なプラグインはモジュールに分割する。
    機能ごとにファイルを分割して保守性を高める。

  • プラグインの初期化処理は軽量に保つ。
    起動時の重い処理はOpenCodeのレスポンス性に影響する可能性がある。



トラブルシューティング

プラグインが読み込まれない場合

プラグインが認識されない場合は、以下の項目を確認する。

配置ディレクトリの確認

プラグインファイルが正しいディレクトリに配置されているか確認する。

  • プロジェクト固有
    .opencode/plugins/
  • グローバル
    ~/.config/opencode/plugins/


ファイル拡張子の確認

プラグインファイルの拡張子が .ts または .js であることを確認する。
他の拡張子のファイルは自動読み込みの対象外である。

ログレベルの設定

OpenCodeのログレベルを DEBUG に設定することにより、詳細な読み込み情報を確認できる。

 OPENCODE_LOG_LEVEL=DEBUG opencode


メモリリークが発生する場合

セッション削除時のクリーンアップが実装されているか確認する。
session.deleted フック内で、セッションに紐付いた全ての状態を削除しているか確認する。

 "session.deleted": async ({ session }) => {
    // Map、Set、その他のデータ構造からセッションのデータを削除する
    mySessionData.delete(session.id)
    myCache.delete(session.id)
 }


依存関係の問題が発生する場合

外部パッケージが見つからないエラーが発生した場合は、以下を確認する。

  • package.jsonファイル.opencode/ディレクトリ に配置されているか確認する。
    プロジェクトルートではなく、.opencode/ 直下に配置する必要がある。

  • bun install が正常に実行されたか確認する。
    手動で bun install を実行して、エラーメッセージを確認する。


cd .opencode && bun install


プラグインの処理が期待通りに動作しない場合

  • デストラクチャリングの記述方法を確認する。
    コンテキストは単一パラメータとしてデストラクチャリングする必要がある。
    正しい記述方法: async ({ client, project }) => { ... }

  • フック名のスペルミスを確認する。
    フック名が誤っていると処理が呼び出されない。
    公式ドキュメントでフック名を確認する。

  • throw の使用状況を確認する。
    tool.execute.before で例外をスローした場合、ツールの実行が中断される。
    意図しない throw がないか確認する。





プラグインマーケットプレイス

OpenCodeはプラグインマーケットプレイス機能を提供しており、コミュニティが提供するプラグインを簡単にインストールできる。

マーケットプレイスからのプラグイン追加

マーケットプレイスからプラグインを追加するには、以下のコマンドを使用する。

 # マーケットプレイスにプラグインを追加
 /plugin marketplace add <マーケットプレイス名>/<プラグイン名>
 
 # 例: Microsoft Docs MCPを追加
 /plugin marketplace add microsoftdocs/mcp


プラグインのインストール

追加したマーケットプレイスからプラグインをインストールするには、以下のコマンドを使用する。

 # プラグインをインストール
 /plugin install <plugin-name>@<marketplace-name>
 
 # 例: Microsoft Docsプラグインをインストール
 /plugin install microsoft-docs@microsoft-docs-marketplace


Microsoft Docs MCPの設定例

Microsoft Docs MCPを使用すると、OpenCodeからMicrosoftおよびAzureの公式ドキュメントにアクセスできる。
公式ドキュメントを検索し、コードサンプルを取得し、詳細な技術情報を参照できる。

 # Microsoft Docs MCPをマーケットプレイスに追加
 /plugin marketplace add microsoftdocs/mcp
 
 # Microsoft Docs プラグインをインストール
 /plugin install microsoft-docs@microsoft-docs-marketplace



よく使用されるプラグイン

OpenCodeのエコシステムには多くのコミュニティプラグインが存在する。

使用される頻度の高い便利なプラグインをカテゴリ別に示す。

認証関連プラグイン

認証関連のプラグインを使用すると、APIクレジットの代わりに既存のサブスクリプションを使用できる。

プラグイン名 説明
opencode-openai-codex-auth ChatGPT Plus/Proのサブスクリプションを使用してOpenAI Codexバックエンドを利用する。
OAuth認証をサポートする。
opencode-gemini-auth 既存のGeminiプランを使用してGoogleアカウントで認証する。
API課金の代わりにGeminiプランを使用できる。
opencode-antigravity-auth Antigravityの無料モデルを使用してAPI課金なしでモデルを利用する。
GeminiおよびAnthropicモデルに対応する。
opencode-google-antigravity-auth Google Antigravity OAuthを使用する拡張版。
Google検索サポートと堅牢なAPI処理を提供する。


開発環境プラグイン

開発環境を拡張するプラグインである。

プラグイン名 説明
opencode-daytona Daytonaサンドボックス内でOpenCodeセッションを自動実行する。
Git同期とライブプレビュー機能を提供する。
opencode-devcontainers 複数ブランチのdevcontainer分離を実現する。
シャロークローンと自動割り当てポートをサポートする。
opencode-morph-fast-apply Morph Fast Apply APIを使用した高速なコード編集を実現する。
10,500+ tokens/secの編集速度と遅延編集マーカーを提供する。
opencode-type-inject ファイル読み込み時にTypeScript/Svelteの型を自動注入する。
型参照ツールを提供する。


エージェント・オーケストレーションプラグイン

AIエージェントの動作を拡張・調整するプラグインである。

プラグイン名 説明
opencode-background-agents Claude Codeスタイルのバックグラウンドエージェントを提供する。
非同期委任とコンテキスト永続化をサポートする。
oh-my-opencode バックグラウンドエージェント、LSP/AST/MCPツール、厳選されたエージェントを提供する。
詳細は専用ページを参照のこと。
micode 構造化されたブレインストーム→計画→実装のワークフローを提供する。
セッション継続性とサブエージェントオーケストレーションをサポートする。
opencode-workspace バンドルされたマルチエージェントオーケストレーションハーネスを提供する。
16コンポーネントを1つのインストールで利用できる。


通知・モニタリングプラグイン

セッション状態の通知や使用状況の追跡を行うプラグインである。

プラグイン名 説明
opencode-notify タスク完了時のネイティブOS通知を提供する。
バックグラウンドタスクの完了を通知する。
opencode-notificator デスクトップ通知とサウンドアラートを提供する。
OpenCodeセッションの状態変化を通知する。
opencode-notifier 権限、完了、エラーイベントのデスクトップ通知とサウンドアラートを提供する。
opencode-wakatime Wakatimeを使用してOpenCodeの使用状況を追跡する。
コーディング時間の自動記録を行う。
opencode-quota プロバイダー間のクォータとトークン使用量を追跡する。
自動トースト通知とスラッシュコマンドを提供する。


その他のユーティリティプラグイン

その他の便利なプラグインである。

プラグイン名 説明
opencode-helicone-session リクエストグループ化のためのHeliconeセッションヘッダーを自動注入する。
API使用状況の分析に使用する。
opencode-dynamic-context-pruning トークン使用量を最適化する。
古いツール出力をコンテキストから削除する。
opencode-supermemory Supermemoryを使用してセッション間の永続メモリを提供する。
長期的なコンテキスト保持を実現する。
opencode-agent-memory Lettaエージェントにインスパイアされた永続的な自己編集可能メモリブロックを提供する。
エージェントの記憶を保持する。
opencode-direnv セッション開始時にdirenv環境変数を自動的に読み込む。
Nix flakesとの相性が良い。
opencode-scheduler launchd (Mac) または systemd (Linux) を使用して定期的なジョブをスケジュールする。
cron構文をサポートする。
opencode-websearch-cited 対応プロバイダーのネイティブウェブ検索サポートを追加する。
Google groundedスタイルの引用付き検索を提供する。
opencode-md-table-formatter LLMが生成したMarkdownテーブルを整形する。
テーブルの可読性を向上させる。
opencode-shell-strategy 非対話型シェルコマンドの指示を提供する。
TTY依存操作によるハングを防止する。


プラグインのインストール方法

プラグインをインストールするには、opencode.jsonファイルplugin フィールドにパッケージ名を指定する。

 {
    "$schema": "https://opencode.ai/config.json",
    "plugin": [
       "opencode-wakatime",
       "opencode-notify",
       "@sveltejs/opencode"
    ]
 }


スコープ付きnpmパッケージ (例: @sveltejs/opencode) もサポートされている。

公式エコシステムリソース

OpenCodeのエコシステムに関する情報は、以下のリソースから入手できる。



参考リンク