OpenCodeの設定 - プラグイン - 版の履歴

2026年6月17日 (水) 04:45にWikiによる

2026-06-17T04:45:29Z

2026年2月26日 (木) 21:33にWikiによる

2026-02-26T21:33:14Z

← 古い版		2026年2月27日 (金) 06:33時点における版
716行目:		716行目:
	<center>		<center>
	{\| class="wikitable"		{\| class="wikitable"
	! プラグイン名 !! 説明		! プラグイン名 !! 説明 !! opencode.jsonの設定
	\|-		\|-
	\| opencode-openai-codex-auth \|\| ChatGPT Plus/Proのサブスクリプションを使用してOpenAI Codexバックエンドを利用する。<br>OAuth認証をサポートする。		\| opencode-openai-codex-auth \|\| ChatGPT Plus/Proのサブスクリプションを使用してOpenAI Codexバックエンドを利用する。<br>OAuth認証をサポートする。 \|\| <code>"opencode-openai-codex-auth"</code>
	\|-		\|-
	\| opencode-gemini-auth \|\| 既存のGeminiプランを使用してGoogleアカウントで認証する。<br>API課金の代わりにGeminiプランを使用できる。		\| opencode-gemini-auth \|\| 既存のGeminiプランを使用してGoogleアカウントで認証する。<br>API課金の代わりにGeminiプランを使用できる。 \|\| <code>"opencode-gemini-auth"</code>
	\|-		\|-
	\| opencode-antigravity-auth \|\| Antigravityの無料モデルを使用してAPI課金なしでモデルを利用する。<br>GeminiおよびAnthropicモデルに対応する。		\| opencode-antigravity-auth \|\| Antigravityの無料モデルを使用してAPI課金なしでモデルを利用する。<br>GeminiおよびAnthropicモデルに対応する。 \|\| <code>"opencode-antigravity-auth"</code>
	\|-		\|-
	\| opencode-google-antigravity-auth \|\| Google Antigravity OAuthを使用する拡張版。<br>Google検索サポートと堅牢なAPI処理を提供する。		\| opencode-google-antigravity-auth \|\| Google Antigravity OAuthを使用する拡張版。<br>Google検索サポートと堅牢なAPI処理を提供する。 \|\| <code>"opencode-google-antigravity-auth"</code>
	\|}		\|}
	</center>		</center>
733行目:		733行目:
	<center>		<center>
	{\| class="wikitable"		{\| class="wikitable"
	! プラグイン名 !! 説明		! プラグイン名 !! 説明 !! opencode.jsonの設定
	\|-		\|-
	\| opencode-daytona \|\| Daytonaサンドボックス内でOpenCodeセッションを自動実行する。<br>Git同期とライブプレビュー機能を提供する。		\| opencode-daytona \|\| Daytonaサンドボックス内でOpenCodeセッションを自動実行する。<br>Git同期とライブプレビュー機能を提供する。 \|\| <code>"opencode-daytona"</code>
	\|-		\|-
	\| opencode-devcontainers \|\| 複数ブランチのdevcontainer分離を実現する。<br>シャロークローンと自動割り当てポートをサポートする。		\| opencode-devcontainers \|\| 複数ブランチのdevcontainer分離を実現する。<br>シャロークローンと自動割り当てポートをサポートする。 \|\| <code>"opencode-devcontainers"</code>
	\|-		\|-
	\| opencode-morph-fast-apply \|\| Morph Fast Apply APIを使用した高速なコード編集を実現する。<br>10,500+ tokens/secの編集速度と遅延編集マーカーを提供する。		\| opencode-morph-fast-apply \|\| Morph Fast Apply APIを使用した高速なコード編集を実現する。<br>10,500+ tokens/secの編集速度と遅延編集マーカーを提供する。 \|\| <code>"opencode-fast-apply"</code><br>パッケージ名が異なる
	\|-		\|-
	\| opencode-type-inject \|\| ファイル読み込み時にTypeScript/Svelteの型を自動注入する。<br>型参照ツールを提供する。		\| opencode-type-inject \|\| ファイル読み込み時にTypeScript/Svelteの型を自動注入する。<br>型参照ツールを提供する。 \|\| <code>"@nick-vi/opencode-type-inject"</code><br>スコープ付きパッケージ
	\|}		\|}
	</center>		</center>
750行目:		750行目:
	<center>		<center>
	{\| class="wikitable"		{\| class="wikitable"
	! プラグイン名 !! 説明		! プラグイン名 !! 説明 !! opencode.jsonの設定
	\|-		\|-
	\| opencode-background-agents \|\| Claude Codeスタイルのバックグラウンドエージェントを提供する。<br>非同期委任とコンテキスト永続化をサポートする。		\| opencode-background-agents \|\| Claude Codeスタイルのバックグラウンドエージェントを提供する。<br>非同期委任とコンテキスト永続化をサポートする。 \|\| <code>"@zenobius/opencode-background"</code><br>パッケージ名が異なる
	\|-		\|-
	\| oh-my-opencode \|\| バックグラウンドエージェント、LSP/AST/MCPツール、厳選されたエージェントを提供する。<br>詳細は専用ページを参照のこと。		\| oh-my-opencode \|\| バックグラウンドエージェント、LSP/AST/MCPツール、厳選されたエージェントを提供する。<br>詳細は専用ページを参照のこと。 \|\| <code>"oh-my-opencode"</code>
	\|-		\|-
	\| micode \|\| 構造化されたブレインストーム→計画→実装のワークフローを提供する。<br>セッション継続性とサブエージェントオーケストレーションをサポートする。		\| micode \|\| 構造化されたブレインストーム→計画→実装のワークフローを提供する。<br>セッション継続性とサブエージェントオーケストレーションをサポートする。 \|\| <code>"micode"</code>
	\|-		\|-
	\| opencode-workspace \|\| バンドルされたマルチエージェントオーケストレーションハーネスを提供する。<br>16コンポーネントを1つのインストールで利用できる。		\| opencode-workspace \|\| バンドルされたマルチエージェントオーケストレーションハーネスを提供する。<br>16コンポーネントを1つのインストールで利用できる。 \|\| npmに未公開
	\|}		\|}
	</center>		</center>
767行目:		767行目:
	<center>		<center>
	{\| class="wikitable"		{\| class="wikitable"
	! プラグイン名 !! 説明		! プラグイン名 !! 説明 !! opencode.jsonの設定
	\|-		\|-
	\| opencode-notify \|\| タスク完了時のネイティブOS通知を提供する。<br>バックグラウンドタスクの完了を通知する。		\| opencode-notify \|\| タスク完了時のネイティブOS通知を提供する。<br>バックグラウンドタスクの完了を通知する。 \|\| <code>"opencode-notify"</code>
	\|-		\|-
	\| opencode-notificator \|\| デスクトップ通知とサウンドアラートを提供する。<br>OpenCodeセッションの状態変化を通知する。		\| opencode-notificator \|\| デスクトップ通知とサウンドアラートを提供する。<br>OpenCodeセッションの状態変化を通知する。 \|\| npmに未公開
	\|-		\|-
	\| opencode-notifier \|\| 権限、完了、エラーイベントのデスクトップ通知とサウンドアラートを提供する。		\| opencode-notifier \|\| 権限、完了、エラーイベントのデスクトップ通知とサウンドアラートを提供する。 \|\| <code>"@mohak34/opencode-notifier"</code><br>スコープ付きパッケージ
	\|-		\|-
	\| opencode-wakatime \|\| Wakatimeを使用してOpenCodeの使用状況を追跡する。<br>コーディング時間の自動記録を行う。		\| opencode-wakatime \|\| Wakatimeを使用してOpenCodeの使用状況を追跡する。<br>コーディング時間の自動記録を行う。 \|\| <code>"opencode-wakatime"</code>
	\|-		\|-
	\| opencode-quota \|\| プロバイダー間のクォータとトークン使用量を追跡する。<br>自動トースト通知とスラッシュコマンドを提供する。		\| opencode-quota \|\| プロバイダー間のクォータとトークン使用量を追跡する。<br>自動トースト通知とスラッシュコマンドを提供する。 \|\| <code>"opencode-quota"</code>
	\|}		\|}
	</center>		</center>
786行目:		786行目:
	<center>		<center>
	{\| class="wikitable"		{\| class="wikitable"
	! プラグイン名 !! 説明		! プラグイン名 !! 説明 !! opencode.json設定
	\|-		\|-
	\| opencode-helicone-session \|\| リクエストグループ化のためのHeliconeセッションヘッダーを自動注入する。<br>API使用状況の分析に使用する。		\| opencode-helicone-session \|\| リクエストグループ化のためのHeliconeセッションヘッダーを自動注入する。<br>API使用状況の分析に使用する。 \|\| <code>"opencode-helicone-session"</code>
	\|-		\|-
	\| opencode-dynamic-context-pruning \|\| トークン使用量を最適化する。<br>古いツール出力をコンテキストから削除する。		\| opencode-dynamic-context-pruning \|\| トークン使用量を最適化する。<br>古いツール出力をコンテキストから削除する。 \|\| <code>"@tarquinen/opencode-dcp"</code><br>スコープ付きパッケージ
	\|-		\|-
	\| opencode-supermemory \|\| Supermemoryを使用してセッション間の永続メモリを提供する。<br>長期的なコンテキスト保持を実現する。		\| opencode-supermemory \|\| Supermemoryを使用してセッション間の永続メモリを提供する。<br>長期的なコンテキスト保持を実現する。 \|\| <code>"opencode-supermemory"</code>
	\|-		\|-
	\| opencode-agent-memory \|\| Lettaエージェントにインスパイアされた永続的な自己編集可能メモリブロックを提供する。<br>エージェントの記憶を保持する。		\| opencode-agent-memory \|\| Lettaエージェントにインスパイアされた永続的な自己編集可能メモリブロックを提供する。<br>エージェントの記憶を保持する。 \|\| <code>"opencode-agent-memory"</code>
	\|-		\|-
	\| opencode-direnv \|\| セッション開始時にdirenv環境変数を自動的に読み込む。<br>Nix flakesとの相性が良い。		\| opencode-direnv \|\| セッション開始時にdirenv環境変数を自動的に読み込む。<br>Nix flakesとの相性が良い。 \|\| npmに未公開
	\|-		\|-
	\| opencode-scheduler \|\| launchd (Mac) または systemd (Linux) を使用して定期的なジョブをスケジュールする。<br>cron構文をサポートする。		\| opencode-scheduler \|\| launchd (Mac) または systemd (Linux) を使用して定期的なジョブをスケジュールする。<br>cron構文をサポートする。 \|\| <code>"opencode-scheduler"</code>
	\|-		\|-
	\| opencode-websearch-cited \|\| 対応プロバイダーのネイティブウェブ検索サポートを追加する。<br>Google groundedスタイルの引用付き検索を提供する。		\| opencode-websearch-cited \|\| 対応プロバイダーのネイティブウェブ検索サポートを追加する。<br>Google groundedスタイルの引用付き検索を提供する。 \|\| <code>"opencode-websearch-cited"</code>
	\|-		\|-
	\| opencode-md-table-formatter \|\| LLMが生成したMarkdownテーブルを整形する。<br>テーブルの可読性を向上させる。		\| opencode-md-table-formatter \|\| LLMが生成したMarkdownテーブルを整形する。<br>テーブルの可読性を向上させる。 \|\| <code>"@franlol/opencode-md-table-formatter"</code><br>スコープ付きパッケージ
	\|-		\|-
	\| opencode-shell-strategy \|\| 非対話型シェルコマンドの指示を提供する。<br>TTY依存操作によるハングを防止する。		\| opencode-shell-strategy \|\| 非対話型シェルコマンドの指示を提供する。<br>TTY依存操作によるハングを防止する。 \|\| npmに未公開
	\|}		\|}
	</center>		</center>
	<br>		<br>
	==== プラグインのインストール方法 ====		==== プラグインのインストール方法 ====
	プラグインをインストールするには、<u>opencode.jsonファイル</u> の <~~code~~>plugin</~~code~~> フィールドにパッケージ名を指定する。<br>		プラグインをインストールするには、<u>opencode.jsonファイル</u> の <u>plugin</u> フィールドにパッケージ名を指定する。<br>
	<br>		<br>
	<syntaxhighlight lang="json">		<syntaxhighlight lang="json">

2026年2月26日 (木) 21:06にWikiによる

2026-02-26T21:06:40Z

差分を表示

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

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

2026-02-20T13:25:23Z

ページの作成:「== 概要 == OpenCodeのプラグインシステムは、TypeScript / JavaScriptで記述したソースコードをOpenCodeの動作に組み込み、独自の機能拡張を実現する仕組みである。 プラグインはフック (hook) ベースのイベント駆動型アーキテクチャを採用しており、 セッションの開始・終了、ファイル操作、ツール実行、シェルコマンドの実行といった各種イベン…」

新規ページ

== 概要 ==
OpenCodeのプラグインシステムは、TypeScript / JavaScriptで記述したソースコードをOpenCodeの動作に組み込み、独自の機能拡張を実現する仕組みである。 
 
プラグインはフック (hook) ベースのイベント駆動型アーキテクチャを採用しており、 
セッションの開始・終了、ファイル操作、ツール実行、シェルコマンドの実行といった各種イベントに対して処理を追加できる。 
 
プラグインが提供する主な機能は以下の通りである。 
* セッション管理の拡張
*: セッションの作成・削除・アイドル状態等のイベントに反応して処理を追加する。
* ツール実行の制御
*: ツール実行前後に検証・変換・ログ記録等の処理を挿入する。
* 環境変数の注入
*: シェル実行時にプロジェクト固有の環境変数を動的に追加する。
* カスタムツールの定義
*: LLMが呼び出せる独自のツールを作成し、OpenCodeの機能を拡張する。
 
プラグインはプロジェクト固有またはグローバルに配置でき、OpenCode起動時に自動的に読み込まれる。 
 

== プラグインの基本構造 ==
プラグインは非同期関数として実装されており、コンテキストオブジェクトを引数として受け取り、フックオブジェクトを返す構造を持つ。 
 
基本的なプラグインの構造を以下に示す。 
 
<syntaxhighlight lang="typescript">
import { Plugin } from "opencode/plugin"

export const MyPlugin: Plugin = async ({ client, project, $, directory }) => {
// 初期化処理をここに記述する

return {
"session.created": async ({ session }) => {
// セッション作成時の処理
},
"tool.execute.before": async ({ tool, args }) => {
// ツール実行前の処理
}
}
}
</syntaxhighlight>
 
コンテキストはデストラクチャリングで受け取ることが重要である。 
 
* 正しい記述方法
*: <code>async ({ client, project, $ }) => { ... }</code>
* 誤った記述方法
*: <code>async (client, project, $) => { ... }</code>
 
==== コンテキストオブジェクト ====
コンテキストオブジェクトには、プラグイン内で利用できる各種情報とAPIが含まれる。 
 
<center>
{| class="wikitable"
! プロパティ !! 説明
|-
| <code>client</code> || OpenCode SDKクライアント ログ出力やAPI呼び出しに使用する。 例: <code>client.app.log("info", "メッセージ")</code>
|-
| <code>project</code> || プロジェクト情報 現在のプロジェクトのメタデータにアクセスできる。
|-
| <code>$</code> || シェルコマンド実行用のAPI (BunのShell API) プラグイン内からシェルコマンドを実行する時に使用する。
|-
| <code>directory</code> || 現在の作業ディレクトリのパス
|-
| <code>worktree</code> || ワークツリー情報 Gitのワークツリーに関する情報にアクセスできる。
|-
| <code>app</code> || アプリケーション参照 OpenCodeアプリケーション全体への参照を提供する。
|}
</center>
 
==== フックオブジェクト ====
フックオブジェクトは、プラグインが対応する各イベントとその処理関数をマッピングしたオブジェクトである。 
 
フックオブジェクトの基本的な構造を以下に示す。 
 
<syntaxhighlight lang="typescript">
return {
// イベント名: 処理関数
"session.created": async ({ session }) => { ... },
"tool.execute.before": async ({ tool, args }) => { ... },
"shell.env": async ({ env }) => { ... }
}
</syntaxhighlight>
 
フックの処理関数は非同期関数として定義して、イベントに応じたパラメータを受け取る。 
 
一部のフックでは、受け取ったパラメータを変更して返すことにより、OpenCodeの動作を変更できる。 
 

== ディレクトリ構造 ==
プラグインは以下の2つの場所に配置できる。 
 
* プロジェクト固有のプラグイン
*: .opencode/plugins/
*: 特定のプロジェクトにのみ適用される。
* グローバルプラグイン
*: ~/.config/opencode/plugins/
*: 全てのプロジェクトで使用できる。
 
OpenCode起動時に上記のディレクトリが自動的にスキャンされ、プラグインが読み込まれる。 
 
npmパッケージとして配布されているプラグインは、opencode.jsonファイル の plugins フィールドに指定することで使用できる。 
 
<syntaxhighlight lang="json">
{
"plugins": [
"opencode-plugin-example",
"./local-plugin"
]
}
</syntaxhighlight>
 
プロジェクトにプラグインを追加する場合の推奨ディレクトリ構成を以下に示す。 
 
<syntaxhighlight lang="bash">
# 例: QML/C++プロジェクト

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

== プラグインの作成方法 ==
==== 基本的なプラグイン ====
最もシンプルなプラグインの例を以下に示す。 
 
以下に示すプラグインは、セッション作成時にログを出力するだけの基本的な実装である。 
 
* ファイルの配置場所の例
*: .opencode/plugins/hello.ts
 
<syntaxhighlight lang="typescript">
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}`)
}
}
}
</syntaxhighlight>
 
==== TypeScript / JavaScriptモジュール ====
OpenCodeのプラグインは、TypeScript または JavaScriptで記述できる。 
TypeScriptを使用すると、型チェックによる安全性が向上するため推奨される。 
 
TypeScriptプラグインの例を以下に示す。 
 
<syntaxhighlight lang="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}`)
}
}
}
</syntaxhighlight>
 

== 利用可能なフック ==
==== セッションフック ====
セッションのライフサイクルに関連するフックである。 
 
<center>
{| class="wikitable"
|+ セッションフック一覧
! フック名 !! 説明 !! 用途
|-
| <code>session.created</code> || セッションが新規作成された時 || 初期化処理、ログ記録
|-
| <code>session.updated</code> || セッション情報が更新された時 || 状態の同期
|-
| <code>session.idle</code> || セッションがアイドル状態になった時 || 通知送信、リソース解放
|-
| <code>session.deleted</code> || セッションが削除された時 || クリーンアップ処理 (重要)
|-
| <code>session.status</code> || セッションのステータスが変化した時 || ステータス監視
|-
| <code>session.compacted</code> || セッションがコンパクションされた時 || コンパクション後の処理
|}
</center>
 
<code>session.deleted</code> フックでの状態クリーンアップは、メモリリーク防止のために特に重要である。 
 
==== ファイルフック ====
メッセージとメッセージパーツに関連するフックである。 
 
<center>
{| class="wikitable"
|+ ファイルフック一覧
! フック名 !! 説明
|-
| <code>message.updated</code> || メッセージが更新された時
|-
| <code>message.removed</code> || メッセージが削除された時
|-
| <code>message.part.updated</code> || メッセージパーツが更新された時
|-
| <code>message.part.removed</code> || メッセージパーツが削除された時
|}
</center>
 
==== ツールフック ====
ツールの実行に関連するフックである。 
ツールフックを使用すると、ツール実行前後に処理を追加したり、実行を制御したりできる。 
 
<center>
{| class="wikitable"
|+ ツールフック一覧
! フック !! 説明
|-
| <code>tool.execute.before</code> || ツール実行前に呼び出される。 入力値の検証や変更が可能である。 <code>throw</code> でツール実行を中断できる。
|-
| <code>tool.execute.after</code> || ツール実行後に呼び出される。 ツールの出力結果に対して後処理を行える。
|}
</center>
 
ツールフックの使用例を以下に示す。 
 
<syntaxhighlight lang="typescript">
"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}`)
}
</syntaxhighlight>
 
==== コマンドフック ====
LLMへのリクエストに関連するフックである。 
 
<center>
{| class="wikitable"
|+ LLMリクエスト関連フック
! フック !! 説明
|-
| <code>chat.params</code> || LLMに送信するパラメータを変更できる。温度設定やシステムプロンプトの動的変更に使用する。
|-
| <code>chat.message</code> || LLMから受信したメッセージに対応する処理を行う。
|}
</center>
 
==== シェルフック ====
シェルコマンドの実行に関連するフックである。 
 
<center>
{| class="wikitable"
|+ LLMリクエスト関連フック
! フック !! 説明
|-
| <code>chat.params</code> || LLMに送信するパラメータを変更できる。 temperature設定やシステムプロンプトの動的変更に使用する。
|-
| <code>chat.message</code> || LLMから受信したメッセージに対応する処理を行う。
|}
</center>
 
<code>shell.env</code> フックの使用例を以下に示す。 
 
<syntaxhighlight lang="typescript">
"shell.env": async ({ env }) => {
return {
...env,
MY_PROJECT_API_URL: "https://api.example.com",
MY_PROJECT_ENV: "development"
}
}
</syntaxhighlight>
 
==== LSPフック ====
Language Server Protocol に関連するフックである。 
 
<center>
{| class="wikitable"
|+ LSP関連フック
! フック !! 説明
|-
| <code>lsp.diagnostics</code> || LSPの診断情報 (エラーや警告) が更新された時に呼び出される。 コード品質の監視や自動修正処理に使用する。
|}
</center>
 
下表に、その他の主要なフックを示す。 
 
<center>
{| class="wikitable"
|+ その他の主要なフック
! フック !! 説明
|-
| <code>permission.ask</code> || 権限確認ダイアログが表示される前に呼び出される。
|-
| <code>permission.replied</code> || 権限確認に対してユーザが返答した後に呼び出される。
|-
| <code>auth</code> || カスタム認証プロバイダを実装する時に使用する。
|}
</center>
 

== カスタムツールの作成 ==
プラグインでは <code>tool()</code> ヘルパー関数を使用してカスタムツールを定義できる。 
 
カスタムツールを定義すると、LLMがそのツールを呼び出してタスクを実行できるようになる。 
 
==== ツールの基本構造 ====
カスタムツールの基本構造を以下に示す。 
 
<syntaxhighlight lang="typescript">
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]
}
}
</syntaxhighlight>
 
==== 引数スキーマ (Zod) ====
カスタムツールの引数スキーマはZodベースのヘルパーを使用して定義する。 
 
利用可能なスキーマ型を以下に示す。 
 
<center>
{| class="wikitable"
|+ 引数スキーマ型一覧
! スキーマ型 !! 説明 !! 使用例
|-
| <code>tool.schema.string()</code> || 文字列型 || ファイルパス、テキスト入力
|-
| <code>tool.schema.number()</code> || 数値型 || カウント、タイムアウト値
|-
| <code>tool.schema.boolean()</code> || 真偽値型 || フラグ、スイッチ
|-
| <code>tool.schema.enum([...])</code> || 列挙型 || 選択肢から1つを選ぶ引数
|-
| <code>tool.schema.optional(...)</code> || 省略可能な型 || 必須でない引数をラップする
|}
</center>
 
各スキーマ型に <code>.describe()</code> を連結することで、LLMへの説明を追加できる。 
説明は詳細に記述するほど、LLMがツールを正しく使用しやすくなる。 
 
<syntaxhighlight lang="typescript">
parameters: {
path: tool.schema.string().describe("操作対象のファイルパス (絶対パスで指定)"),
mode: tool.schema.enum(["read", "write", "append"]).describe("ファイル操作のモード"),
encoding: tool.schema.optional(tool.schema.string()).describe("文字エンコーディング (省略時はUTF-8)")
}
</syntaxhighlight>
 
==== 複数ツールのエクスポート ====
1つのプラグインから複数のカスタムツールをエクスポートするには、<code>tools</code> フィールドに配列で指定する。 
 
<syntaxhighlight lang="typescript">
return {
tools: [toolA, toolB, toolC]
}
</syntaxhighlight>
 
==== コンテキストアクセス ====
<code>execute</code> 関数の第2引数 <code>context</code> から、実行時の情報にアクセスできる。 
 
<center>
{| class="wikitable"
|+ コンテキストプロパティ一覧
! プロパティ !! 説明
|-
| <code>context.sessionID</code> || 現在のセッションID
|-
| <code>context.messageID</code> || 現在のメッセージID
|-
| <code>context.directory</code> || 現在の作業ディレクトリ
|-
| <code>context.worktree</code> || ワークツリー情報
|-
| <code>context.agent</code> || 実行中のエージェント情報
|-
| <code>context.signal</code> || キャンセル用のAbortSignal
|}
</center>
 
<code>context.signal</code> を使用することにより、長時間処理の途中でキャンセルに対応できる。 
 

== プラグインの実用例 ==
==== 環境変数保護 ====
機密ファイル (環境変数ファイル、認証情報ファイル等) へのアクセスを禁止するプラグインの実装例を以下に示す。 
 
* ファイルの配置場所の例
*: .opencode/plugins/env-protection.ts
 
<syntaxhighlight lang="typescript">
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")
}
}
}
}
</syntaxhighlight>
 
このプラグインは、<code>read</code> ツールが機密ファイルにアクセスしようとした時に例外をスローして処理を中断する。 
 
==== セッション通知 ====
セッションがアイドル状態になった時にログを出力するプラグインの実装例を以下に示す。 
この例を応用することで、外部の通知サービスへの連携も実現できる。 
 
* ファイルの配置場所の例
*: .opencode/plugins/notification.ts
 
<syntaxhighlight lang="typescript">
import { Plugin } from "opencode/plugin"

export const NotificationPlugin: Plugin = async ({ client }) => {
return {
"session.idle": async ({ session }) => {
client.app.log("info", "Session completed")
// ここに外部通知サービスへのAPI呼び出し等を追加できる
}
}
}
</syntaxhighlight>
 
==== カスタムツール定義 ====
プロジェクト固有のカスタムツールを定義するプラグインの実装例を以下に示す。 
この例では、指定したファイルのメタデータ (行数、サイズ等) を取得するツールを定義している。 
 
* ファイルの配置場所の例
*: .opencode/plugins/custom-tools.ts
 
<syntaxhighlight lang="typescript">
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]
}
}
</syntaxhighlight>
 

== 依存関係の管理 ==
プラグインで外部npmパッケージを使用する場合は、.opencode/package.jsonファイル に依存関係を定義する。 
 
<syntaxhighlight lang="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"
}
}
</syntaxhighlight>
 
OpenCodeの起動時に <code>bun install</code> コマンドが自動的に実行されるため、手動でインストールコマンドを実行する必要はない。 
 
依存関係の管理に関する注意事項を以下に示す。 
* package.jsonファイル は、必ず .opencode/ディレクトリ に配置する。
*: プロジェクトルートの package.jsonファイル とは別ファイルである。
*: 
* Bunが使用されるため、npm、yarn、pnpmとは異なる場合がある。
*: Bunに対応したパッケージを使用することを確認する。
* TypeScriptを使用する場合は、型定義パッケージ (@types/*) も依存関係に含める。
 

== 推奨される事柄 ==
==== エラーハンドリング ====
プラグインのフック内では、適切なエラーハンドリングを実装する。 
 
エラーが発生した場合でも、OpenCodeの動作が停止しないように注意する。 
 
<syntaxhighlight lang="typescript">
"session.created": async ({ session }) => {
try {
await initializeSession(session.id)
}
catch (error) {
client.app.log("error", `セッション初期化エラー: ${error}`)
// エラーを再スローしないことで、OpenCodeの動作を継続させる
}
}
</syntaxhighlight>
 
==== セッション削除時のクリーンアップ ====
セッションごとに状態を保持する場合は、<code>session.deleted</code> フックで必ずクリーンアップを行う。 
クリーンアップを怠るとメモリリークの原因となる。 
 
<syntaxhighlight lang="typescript">
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)
}
}
}
</syntaxhighlight>
 
==== ログ出力 ====
プラグイン内のログ出力は <code>console.log()</code> ではなく、<code>client.app.log()</code> を使用する。 
<code>client.app.log()</code> を使用することにより、OpenCodeのログシステムと統合されて適切に管理される。 
 
<syntaxhighlight lang="typescript">
// 正しい方法
client.app.log("info", "処理完了")
client.app.log("error", "エラーが発生しました")
client.app.log("debug", "デバッグ情報")

// 避けるべき方法
console.log("処理完了")
</syntaxhighlight>
 
==== その他のベストプラクティス ====
* TypeScriptを使用して型安全性を確保する。
*: TypeScriptの型チェックにより、ランタイムエラーを事前に防止できる。
*: 
* 公式フックのみを使用する。
*: 非公式・内部フックは将来のバージョンで変更される可能性がある。
*: 
* 大規模なプラグインはモジュールに分割する。
*: 機能ごとにファイルを分割して保守性を高める。
*: 
* プラグインの初期化処理は軽量に保つ。
*: 起動時の重い処理はOpenCodeのレスポンス性に影響する可能性がある。
 

== トラブルシューティング ==
==== プラグインが読み込まれない場合 ====
プラグインが認識されない場合は、以下の項目を確認する。 
 
===== 配置ディレクトリの確認 =====
プラグインファイルが正しいディレクトリに配置されているか確認する。 
 
* プロジェクト固有
*: .opencode/plugins/
* グローバル
*: ~/.config/opencode/plugins/
 
===== ファイル拡張子の確認 =====
プラグインファイルの拡張子が .ts または .js であることを確認する。 
他の拡張子のファイルは自動読み込みの対象外である。 
 
===== ログレベルの設定 =====
OpenCodeのログレベルを <code>DEBUG</code> に設定することにより、詳細な読み込み情報を確認できる。 
 
<syntaxhighlight lang="sh">
OPENCODE_LOG_LEVEL=DEBUG opencode
</syntaxhighlight>
 
==== メモリリークが発生する場合 ====
セッション削除時のクリーンアップが実装されているか確認する。 
<code>session.deleted</code> フック内で、セッションに紐付いた全ての状態を削除しているか確認する。 
 
<syntaxhighlight lang="typescript">
"session.deleted": async ({ session }) => {
// Map、Set、その他のデータ構造からセッションのデータを削除する
mySessionData.delete(session.id)
myCache.delete(session.id)
}
</syntaxhighlight>
 
==== 依存関係の問題が発生する場合 ====
外部パッケージが見つからないエラーが発生した場合は、以下を確認する。 
 
* package.jsonファイル が .opencode/ディレクトリ に配置されているか確認する。
*: プロジェクトルートではなく、<code>.opencode/</code> 直下に配置する必要がある。
*: 
* <code>bun install</code> が正常に実行されたか確認する。
*: 手動で <code>bun install</code> を実行して、エラーメッセージを確認する。
 
cd .opencode && bun install
 
==== プラグインの処理が期待通りに動作しない場合 ====
* デストラクチャリングの記述方法を確認する。
*: コンテキストは単一パラメータとしてデストラクチャリングする必要がある。
*: 正しい記述方法: <code>async ({ client, project }) => { ... }</code>
*: 
* フック名のスペルミスを確認する。
*: フック名が誤っていると処理が呼び出されない。
*: 公式ドキュメントでフック名を確認する。
*: 
* <code>throw</code> の使用状況を確認する。
*: <code>tool.execute.before</code> で例外をスローした場合、ツールの実行が中断される。
*: 意図しない <code>throw</code> がないか確認する。
 

== 参考リンク ==
* [https://opencode.ai/docs OpenCode公式ドキュメント]
* [https://opencode.ai/docs/plugins OpenCode公式ドキュメント - Plugins]
* [https://github.com/opencode-ai/opencode OpenCode GitHubリポジトリ]
 

{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,OpenCode,Plugin,TypeScript,JavaScript,Hook,Tool,AI,Development,Programming,SUSE,Linux
|description={{PAGENAME}} - OpenCodeのプラグインシステムに関する設定・実装ガイド | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]