Contents
OpenClaw の全体像とプラグインモデル
OpenClaw は「コア本体 + サンドボックス化されたプラグイン」という二層構造で動作する、自己学習型 AI アシスタントです。コアはエージェント・スケジューラ・外部サービスとのブリッジを提供し、機能拡張はすべて プラグイン として独立したプロセスで実装します。この設計により、プラグイン同士の衝突や本体への不正アクセスを防ぎつつ、柔軟なカスタマイズが可能です。以下では、主要コンポーネントとプラグインの役割を整理します。
コアコンポーネント
OpenClaw の中核となる機能は次の 3 つに分かれます。
| コンポーネント | 主な責務 |
|---|---|
| エージェント | LLM と対話し、自然言語からタスクオブジェクトを生成 |
| スケジューラ | バックグラウンドジョブや定期実行タスクを管理 |
| プロトコル層 | HTTP・WebSocket など外部サービスとの通信窓口を提供 |
プラグインの位置付け
プラグインはサンドボックス内で動作し、ホストが公開する 限定 API を通じてやり取りします。代表的な活用例は次のとおりです。
- UI フック – メニュー追加や独自ダイアログ表示
- データパイプライン拡張 – 入力前処理・出力後加工
- カスタムツール – 認可フックや外部 API ラッパー
公式ドキュメント（https://openclaw.ai/）でも「プラグインはサンドボックスで実行され、ホストとの通信は許可された API のみ」という方針が明記されています。これを守ることでセキュリティと安定性の両立が実現できます。
開発環境のセットアップ（初心者向け）
この章では、プラグイン開発に必要なツールを 0 から構築 する手順を示します。Node.js と OpenClaw CLI の最新バージョンを取得し、プロジェクト雛形を自動生成できるまでの流れです。初心者でも数分で作業を開始できるよう配慮しています。
Node.js と OpenClaw CLI のインストール
2026 年 4 月時点で推奨されている LTS バージョンは Node.js v22、OpenClaw CLI は v1.4 系 が最新です。常に公式サイト（https://nodejs.org/、https://openclaw.ai/docs/cli）で最新版を確認してください。
インストール手順（macOS / Linux）
|
1 2 3 4 5 6 7 8 |
# Node.js v22 を取得しパスへ追加 curl -fsSL https://nodejs.org/dist/v22.0.0/node-v22.0.0-linux-x64.tar.xz | tar -xJf - export PATH=$(pwd)/node-v22.0.0-linux-x64/bin:$PATH # OpenClaw CLI のグローバルインストール npm i -g @openclaw/cli openclaw --version # 例: 1.4.2 |
インストール手順（Windows PowerShell）
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# Node.js ダウンロード & 展開 Invoke-WebRequest https://nodejs.org/dist/v22.0.0/node-v22.0.0-win-x64.zip -OutFile node.zip Expand-Archive .\node.zip -DestinationPath $env:ProgramFiles\nodejs # パスを永続化（管理者権限が必要） [Environment]::SetEnvironmentVariable('PATH', "$env:ProgramFiles\nodejs;$env:PATH", [EnvironmentVariableTarget]::Machine) # CLI のインストール npm i -g @openclaw/cli openclaw --version # 確認 |
プロジェクト雛形の生成と基本設定
CLI が提供する openclaw plugins init コマンドで、ベストプラクティスに沿ったテンプレートが自動作成されます。以下は実行例です。
|
1 2 3 |
mkdir my-plugin && cd my-plugin openclaw plugins init --template typescript |
生成されたディレクトリ構造（抜粋）は次の通りです。
|
1 2 3 4 5 6 7 8 9 10 |
my-plugin/ ├─ src/ │ ├─ index.ts # エントリポイント │ └─ manifest.json # 権限・メタ情報（JSON） ├─ test/ │ └─ plugin.test.ts ├─ tsconfig.json ├─ .eslintrc.js └─ package.json |
tsconfig.json の推奨設定
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{ "compilerOptions": { "target": "ES2022", "module": "CommonJS", "strict": true, "noImplicitAny": true, "esModuleInterop": true, "skipLibCheck": true, "outDir": "./dist" }, "include": ["src/**/*.ts", "test/**/*.ts"] } |
ESLint 設定例
|
1 2 3 4 5 6 7 8 |
module.exports = { env: { node: true, es2022: true }, extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'], parser: '@typescript-eslint/parser', plugins: ['@typescript-eslint'], rules: { 'no-console': 'warn' } }; |
これらの設定により、型安全・コード品質が担保され、CI パイプラインへの組み込みもスムーズになります。
プラグイン開発の基本フロー
本セクションでは「インストール → 有効化 → 動作 → 無効化 → アンインストール」という 5 段階ライフサイクルを中心に、必須実装ポイントと安全な配布手順をまとめます。重複していた記述は統合し、全体像が把握しやすいよう整理しました。
ライフサイクル別フックの実装
manifest.json に宣言したフック名に対応する関数を src/index.ts で実装します。以下は各フェーズと代表的なフック名です。
| フェーズ | 呼び出しタイミング | 推奨フック |
|---|---|---|
| インストール | ユーザーがプラグインを追加した瞬間 | onInstall |
| 有効化 | ホスト起動時または手動で有効にしたとき | onActivate |
| 実行 | UI イベントや RPC が来たとき | handleEvent, invokeRpc |
| 無効化 | ユーザーがプラグインをオフにしたとき | onDeactivate |
| アンインストール | 完全に削除されたとき | onUninstall |
サンプルコード（src/index.ts）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
import { PluginContext, onInstall, onActivate, onDeactivate, onUninstall, } from '@openclaw/plugin-sdk'; export const manifest = { name: 'sample-plugin', version: '0.1.0', // JSON のみで記述し、コメントは入れない permissions: ['read:user', 'invoke:rpc'] }; @onInstall() export async function install(ctx: PluginContext) { await ctx.storage.set('installedAt', new Date().toISOString()); } @onActivate() export async function activate(ctx: PluginContext) { ctx.registerCommand('sample.hello', async () => 'Hello from Sample Plugin'); } |
最小権限の設定と署名ベストプラクティス
権限は「最小特権」原則で記述する
manifest.json の permissions 配列には、本当に必要な項目だけを列挙します。過剰に広い権限はユーザーから警告が出る原因となります。
|
1 2 3 4 5 6 7 8 9 |
{ "name": "sample-plugin", "version": "0.1.0", "permissions": [ "read:user", // プロフィール取得のみ許可 "invoke:rpc" // RPC 呼び出し限定 ] } |
署名フロー（重複排除）
- 鍵ペアの生成
bash
openclaw plugins gen-keypair --out ./keys - パッケージ化と署名（
npm pack後に実行）
bash
npm pack # dist/sample-plugin-0.1.0.tgz が生成
openclaw plugins sign dist/sample-plugin-0.1.0.tgz --key ./keys/private.pem - ホスト側での検証（開発者は
openclaw plugins verifyで事前確認）
bash
openclaw plugins verify dist/sample-plugin-0.1.0.tgz --public-key ./keys/public.pem
署名が付与されたプラグインだけがホストにロードされ、改ざん検知が自動的に行われます。公式ガイド（https://openclaw.ai/docs/plugins/security）でも同様の手順が推奨されています。
通信パターンと非同期設計
プラグインはホストや外部サービスとの通信方式を選択できます。本節では代表的な 4 パターンを比較し、実装上の注意点を示します。特に 非同期 RPC のタイムアウト処理は必須です。
パターン別特徴とユースケース
| パターン | 特徴 | 向いているシナリオ |
|---|---|---|
| イベント駆動 | ホストが発行する event をプラグイン側でリスン。低レイテンシ・単方向通信 |
UI ボタン操作、ステータス変化通知 |
| 同期 RPC | 呼び出し元が即座に結果を取得。ブロッキングになるため高速処理向き | 設定取得、簡易計算 |
| 非同期 RPC | Promise で結果待ち。タイムアウトやリトライ制御が必要 |
外部 API 呼び出し、長時間タスク |
| HTTP / WebSocket | プラグインが独自に外部サービスと接続。双方向・ストリーミングが可能 | リアルタイムチャット、データストリーム |
非同期 RPC のタイムアウトユーティリティ
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
export async function rpcWithTimeout<T>(fn: () => Promise<T>, ms: number): Promise<T> { return Promise.race([ fn(), new Promise<never>((_, reject) => setTimeout(() => reject(new Error('RPC timeout')), ms) ), ]); } // 使用例（5 秒でタイムアウト） const result = await rpcWithTimeout( () => ctx.invokeRpc('external.fetch', { url: 'https://api.example.com' }), 5000 ); |
エラーハンドリングと共通エラー型
プラグイン全体で同一形式のエラーオブジェクトを返すことで、ホスト側の UI 表示やリトライロジックが統一的に扱えます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
export class PluginError extends Error { constructor(public code: string, public details?: any) { super(details?.message ?? code); this.name = 'PluginError'; } } // 呼び出し側の例 try { await rpcWithTimeout(() => ctx.invokeRpc('db.query', { sql: 'SELECT …' }), 4000); } catch (e) { if (e instanceof PluginError) { ctx.logger.warn(`Plugin error ${e.code}: ${e.message}`); } else { ctx.logger.error('Unexpected error', e); } } |
ベストプラクティス
デフォルトタイムアウトは 3–5 秒 に設定し、長時間処理はバックグラウンドジョブ化する。
エラーコードはプレフィックス（例：PLUGIN_, RPC_）で統一し、ドキュメントに列挙しておく。
テスト・デバッグ・公開までの実践ガイド
本章ではローカルテストから CI 設定、最終的なパッケージ化・署名・ClawHub 公開までのフローを具体例付きで解説します。初心者でも「コードを書いたらすぐにリリースできる」ことが目標です。
ローカルテストとデバッグ手法
CLI デバッグモード
|
1 2 |
openclaw plugins run --debug --plugin ./dist/sample-plugin-0.1.0.tgz |
--debug を付けると Node の inspect ポートが自動的に開かれ、VS Code 等のデバッガーからブレークポイントが設定可能です。
Jest を用いたユニットテスト例
|
1 2 3 4 5 6 7 8 9 10 11 12 |
// test/plugin.test.ts import { activate } from '../src/index'; import { MockContext } from '@openclaw/plugin-sdk/testing'; test('activate registers hello command', async () => { const ctx = new MockContext(); await activate(ctx); expect(ctx.commands).toContainEqual( expect.objectContaining({ name: 'sample.hello' }) ); }); |
GitHub Actions による CI 設定（抜粋）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
name: CI on: push: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node uses: actions/setup-node@v3 with: node-version: '22' # 最新 LTS を使用 - run: npm ci - run: npm run lint - run: npm test |
パッケージ化・署名・ClawHub への公開
-
パッケージ化
bash
npm pack # → dist/sample-plugin-0.1.0.tgz が生成 -
署名付与（前述の鍵ペアを使用）
bash
openclaw plugins sign dist/sample-plugin-0.1.0.tgz --key ./keys/private.pem -
ClawHub へ公開（公式レジストリ）
bash
openclaw plugins publish dist/sample-plugin-0.1.0.tgz \
--api-key $CLAWHUB_API_KEY \
--description "サンプルプラグイン – UI フックと非同期 RPC のデモ"
公開後は ClawHub ダッシュボードでバージョン履歴、ダウンロード数、ユーザーレビューが確認できます。公式 API キーの取得方法は https://openclaw.ai/docs/clawhub/auth に記載されています。
最終チェックリスト
| 項目 | 確認内容 |
|---|---|
| 環境 | Node.js v22 以上、@openclaw/cli 最新版がインストール済み |
| 雛形生成 | openclaw plugins init により作成された構成がそのまま残っている |
| TypeScript 設定 | tsconfig.json と .eslintrc.js がプロジェクト直下に存在 |
| ライフサイクル実装 | onInstall / onActivate / onDeactivate / onUninstall が正しくデコレートされている |
| 権限マニフェスト | 必要最小限の permissions のみが列挙され、JSON 形式で正しいか |
| 署名 | 鍵ペアで生成した署名が付与され、openclaw plugins verify が成功 |
| テスト | ユニットテストがすべてパスし、CI が通過している |
| デバッグ | openclaw plugins run --debug で期待どおりに動作する |
| 公開手順 | npm pack → sign → publish の流れを実行できたか |
この項目をすべてクリアすれば、OpenClaw プラグインの 開発から公式リポジトリへの公開まで を自力で完結できます。
まとめ
本稿では OpenClaw の全体像、初心者向け環境構築、プラグイン開発フロー、通信設計、テスト・デバッグ・公開手順を網羅的に解説しました。外部リンクは公式ドキュメントのみ使用し、バージョン情報は「最新」を参照する形で記載しています。ぜひこのガイドを手元に置き、実際のプラグイン開発に活用してください。