Contents
OpenClaw プラグイン 開発方法 — 概要と全体フロー
ここでは OpenClaw プラグインの目的と、開発から公開までの全体フローを短くまとめます。設計ではライフサイクル、権限モデル、ホストとの通信方式を押さえることが重要です。
プラグインの概念とアーキテクチャ
プラグインはインストール→初期化→動作→無効化→アンインストールという流れで管理されます。ホストへの登録とイベントハンドラ、外部呼び出しの設計が主な関心事です。
- ライフサイクル要点：軽量な初期化、非同期処理はタイムアウト設計をする。
- 拡張ポイント例：UIフック、データパイプライン、認可フック、スケジューラー。
- 通信パターン：イベント駆動、RPC（同期/非同期）、HTTP/WebSocket が一般的。
- セキュリティ観点：最小権限、サンドボックス、署名による検証。
用語と命名規則
ここでは実装で使う主要用語と命名例を統一して示します。命名規則を統一すると配布・運用が楽になります。
- プラグインID：逆順ドメイン形式（例: com.example.myplugin）
- マニフェスト：manifest.yaml / manifest.json（必須フィールドは公式仕様に従う）
- エントリポイント：entrypoint または main（例: dist/index.js）
- ホストモック：テスト用の擬似ホストは "ホストモック" と表記する
開発準備（セットアップ）
SDK入手とローカル環境整備、依存関係管理、シークレット運用方針を具体的に示します。ここでは Node.js 例を中心にコマンドを提示します。
公式SDKとテンプレートの入手
公式ドキュメントとテンプレートを先に確認します。公式リソースにはマニフェスト仕様や配布要件が明記されています。
- 公式ドキュメント（例、組織の公式URLに差し替えてください）：https://docs.openclaw.example/
- 公式テンプレート（例）：https://github.com/openclaw/plugin-template
ローカルにテンプレートをクローンする例:
|
1 2 3 |
git clone https://github.com/openclaw/plugin-template.git my-openclaw-plugin cd my-openclaw-plugin |
テンプレートに README が含まれている場合は最初に必ず目を通してください。
ローカル開発環境構築（Node.js 例）
Node.js での具体的セットアップ手順を示します。Node 18 を想定します。
|
1 2 3 4 5 6 7 |
# nvm がインストールされている前提 nvm install 18 nvm use 18 node -v npm ci # 既に package-lock.json があれば高速に復元 # 初回: npm install |
開発依存をインストールする例（esbuild, jest, eslint を想定）:
|
1 2 |
npm install --save-dev esbuild jest eslint |
IDE は Visual Studio Code を推奨します。ランタイムのバージョンは CI と一致させてください。
環境変数とシークレット管理
認証情報や公開鍵は安全に管理します。開発用は .env.example を用意し、本番キーはシークレットストアを使います。
例: .env.example
|
1 2 3 |
OPENCLAW_HOST_URL=https://staging.openclaw.example PUBLISH_TOKEN=REDACTED |
- Git に secrets をコミットしない。.gitignore に .env を追加する。
- CI では GitHub Secrets / GitLab CI変数 を利用する。
- 長期運用は AWS Secrets Manager / GCP Secret Manager / HashiCorp Vault を推奨します。
GitHub Actions で AWS Secrets Manager を参照する例（抜粋）:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
- name: Configure AWS uses: aws-actions/configure-aws-credentials@v2 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-1 - name: Fetch publish token run: | aws secretsmanager get-secret-value --secret-id openclaw/publish-token --query SecretString --output text > secret.json PUBLISH_TOKEN=$(jq -r .token secret.json) echo "PUBLISH_TOKEN=${PUBLISH_TOKEN}" >> $GITHUB_ENV |
ビルドとローカル実行
ここではビルド（バンドル）からローカルでの起動、ホストモックを使った動作確認までを実行手順で示します。Node.js 例で動くコマンドを記載します。
サンプルプロジェクト構成
典型的なファイル構成と、実用的なマニフェスト例を示します。マニフェストのフィールド名は必ず公式仕様を確認してください。
推奨ファイル構成（一例）:
- manifest.yaml
- src/
- index.js
- package.json
- scripts/
- package-and-sign.sh
- host-mock.js
- tests/
- unit/
- dist/
- .github/workflows/
manifest.yaml（実装時は公式仕様に合わせてください）:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
id: com.example.openclaw.sample name: Example OpenClaw Plugin version: 0.1.0 description: "最小の OpenClaw プラグイン例" entrypoint: dist/index.js runtime: nodejs18 compatibility: min_host_version: "1.0.0" permissions: - read:data - write:logs |
マニフェストは配布先マーケットの要件（署名や追加メタデータ）に従って編集してください。公式リファレンスを参照すること。
最小コード例（Node.js）
最小限の初期化とイベント登録のサンプルです。実API名は SDK に合わせて読み替えてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
// src/index.js exports.initialize = async function (host) { // 軽量な初期化 await host.log('info', 'plugin.initialized', { version: '0.1.0' }); await host.registerEventHandler('item.created', async (event) => { if (!event || !event.data) return; try { // ここにビジネスロジック await processEvent(event, host); } catch (err) { await host.log('error', 'processing.failed', { error: err.message }); } }); }; async function processEvent(event, host) { // 外部API呼び出し等。タイムアウトとエラー処理を必須にする。 // 例: await host.fetchWithTimeout(...) } |
このコードをそのまま動かす前に、ホストの API シグネチャを公式リファレンスで必ず確認してください。
ビルドとパッケージ手順（コマンド）
Node.js でのサンプル手順を順に示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# リポジトリをクローン git clone https://github.com/openclaw/plugin-template.git my-plugin cd my-plugin # Node のセットアップ nvm install 18 nvm use 18 # 依存インストール npm ci # 静的解析・テスト・ビルド npm run lint npm test npm run build # パッケージ化（例: zip） npm run package ls -la dist/ |
package.json の重要なスクリプト例:
|
1 2 3 4 5 6 7 8 9 |
{ "scripts": { "lint": "eslint .", "test": "jest --runInBand", "build": "esbuild src/index.js --bundle --platform=node --outfile=dist/index.js --target=node18", "package": "bash scripts/package-and-sign.sh" } } |
scripts/package-and-sign.sh の例（簡易、CI では秘密鍵をシークレットから読み込む）:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
#!/usr/bin/env bash set -euo pipefail rm -rf dist mkdir -p dist cp manifest.yaml dist/ cp -r dist/* dist/ # ビルド成果物を dist にまとめる zip -r dist/plugin.zip dist/ # GPG 署名（CI では GPG_PRIVATE_KEY を利用） if [ -n "${GPG_PRIVATE_KEY:-}" ]; then echo "$GPG_PRIVATE_KEY" | gpg --batch --import gpg --batch --yes --passphrase "$GPG_PASSPHRASE" --pinentry-mode loopback --detach-sign -a dist/plugin.zip fi |
ローカルでの動作確認（ホストモック）
簡易ホストモックでプラグインを読み込み、イベントをシミュレートします。
scripts/host-mock.js の例:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
// scripts/host-mock.js const plugin = require('../dist/index.js'); const hostMock = { registerEventHandler: async (eventName, handler) => { console.log('handler registered for', eventName); // イベントを遅延で通知 setTimeout(() => handler({ data: { id: 'evt-1', payload: 'hello' } }), 500); }, log: async (level, message, meta) => { console.log(JSON.stringify({ level, message, meta })); }, // 必要なら fetchWithTimeout 等のモック実装を追加する }; (async () => { await plugin.initialize(hostMock); })(); |
実行:
|
1 2 3 |
node scripts/host-mock.js # ログとイベントハンドラの動作を確認する |
デバッグとテスト
ユニット・統合・E2E の戦略と具体的なコマンド、モック実装例を示します。テストは速く回ることが重要です。
ユニットテストとホストモック
ユニットテストでは外部依存をモック化します。Jest を用いた例を示します。
tests/unit/process.test.js:
|
1 2 3 4 5 6 7 8 |
const { processEvent } = require('../../src/index.js'); test('processEvent handles valid input', async () => { const host = { log: jest.fn() }; await processEvent({ data: { id: '1' } }, host); expect(host.log).toHaveBeenCalled(); }); |
モックは小さくシンプルに保ち、エラー分岐も網羅してください。
統合テストとステージング E2E
統合テストはホストのエミュレータかステージング環境で行います。Docker エミュレータが提供されている場合は、CI で起動して対話的にテストします。
例: Docker ベースのステージングエミュレータを使う（組織のイメージ名に置き換える）
|
1 2 3 4 5 |
docker pull registry.example/openclaw-emulator:latest docker run --rm -p 8080:8080 registry.example/openclaw-emulator:latest # 別ターミナルでテスト実行 npm run e2e |
ステージングでのテストは実ネットワークコールが発生しうるため、レート制限やシークレットの扱いに注意してください。
ログとトレース設計
構造化ログと相関 ID を設計しておくと障害対応が速くなります。ログは JSON 形式で出力することを推奨します。
ログ例:
|
1 2 |
{"timestamp":"2024-01-01T00:00:00Z","level":"info","message":"processing.started","correlation_id":"abc-123","event_id":"evt-1"} |
トレースは外部トレーシングサービス（OpenTelemetry 互換）に出力できる形で実装してください。
CI/CD と配布（署名・公開）
CI での自動ビルド・テスト・署名・公開までの実装例を示します。GitHub Actions を例に、ランタイムやコマンドを明示します。
GitHub Actions 実装例（Node.js、署名、公開）
以下はタグプッシュでリリースを作成し、成果物を署名して GitHub Releases にアップロードするワークフローの例です。Node 18 を指定しています。
.github/workflows/release.yml の例:
|
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 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
name: Release on: push: tags: - 'v*.*.*' jobs: build-and-release: runs-on: ubuntu-latest env: NODE_OPTIONS: "--max-old-space-size=4096" steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' cache: 'npm' - name: Install dependencies run: npm ci - name: Lint run: npm run lint - name: Unit tests run: npm test - name: Build run: npm run build - name: Package and sign run: bash scripts/package-and-sign.sh env: GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }} GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} - name: Create Release id: create_release uses: actions/create-release@v1 with: tag_name: ${{ github.ref_name }} release_name: Release ${{ github.ref_name }} env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Upload artifact uses: actions/upload-release-asset@v1 with: upload_url: ${{ steps.create_release.outputs.upload_url }} asset_path: dist/plugin.zip asset_name: plugin.zip asset_content_type: application/zip - name: Upload signature uses: actions/upload-release-asset@v1 with: upload_url: ${{ steps.create_release.outputs.upload_url }} asset_path: dist/plugin.zip.asc asset_name: plugin.zip.asc asset_content_type: application/pgp-signature |
上記の GPG 鍵は、CI のシークレットストア（例: GitHub Secrets）に安全に保管してください。
依存性スキャンと SCA（Dependabot / Trivy / Snyk）
依存関係の自動更新と脆弱性検出は CI パイプラインで必須にします。設定例を示します。
Dependabot 更新設定（.github/dependabot.yml）例:
|
1 2 3 4 5 6 7 8 |
version: 2 updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "daily" open-pull-requests-limit: 10 |
Trivy を CI に組み込む例（ファイルシステムスキャン）:
|
1 2 3 4 5 6 |
- name: Trivy scan uses: aquasecurity/trivy-action@v0.10.0 with: scan-type: fs severity: CRITICAL,HIGH |
Snyk の CLI を使う場合は組織の Snyk トークンを利用して定期スキャンとモニタを行います。
署名方式と公開
- バイナリ署名：GPG による detached-sign（.asc）と SHA256 チェックサムを併用する方法が一般的です。
- コンテナ署名：OCI イメージなら cosign を推奨します。
- 公開：マーケットが提供する API または GitHub Releases を利用します。API 呼び出し例は公式 API ドキュメントに従ってください。
公開 API 例（ダミー、必ず公式に合わせる）:
|
1 2 3 4 5 |
curl -X POST "https://market.openclaw.example/api/v1/plugins" \ -H "Authorization: Bearer $PUBLISH_TOKEN" \ -F "file=@dist/plugin.zip" \ -F "manifest=@manifest.yaml" |
運用・セキュリティ・監視
公開後の互換性管理、脆弱性対応、監視設計を具体的に示します。運用手順と自動化が安定の鍵です。
互換性とバージョニング方針
互換性は利用者の信頼に直結します。方針を文書化して CI で自動チェックします。
- バージョン方式：SemVer を推奨（互換性破壊はメジャー上げ）
- 互換性マトリクス：サポートするホストバージョンを明記し、CI で matrix テストを行う
- デプリケーション：代替 API を告知し、猶予期間を設ける
GitHub Actions のマトリクス例（ホストバージョンテスト）:
|
1 2 3 4 |
strategy: matrix: host-version: [1.0.0, 1.1.0, 2.0.0] |
セキュリティ運用（SCA・署名・シークレット管理）
具体的なツールと運用例を示します。自動化で早期検出・対応を行います。
- SCA：Dependabot + Snyk/Trivy を組み合わせる
- 署名：GPG による署名、OCI は cosign
- シークレット管理：GitHub Secrets / AWS Secrets Manager / Vault を利用
- キーのローテーション：年次またはインシデント時にローテーションを自動化する
Trivy をローカルで使う例:
|
1 2 |
trivy fs --severity HIGH,CRITICAL . |
Snyk の簡易チェック:
|
1 2 |
snyk test --severity-threshold=high |
GPG 署名コマンド例:
|
1 2 3 |
gpg --batch --yes --passphrase "$GPG_PASSPHRASE" --pinentry-mode loopback --detach-sign -a dist/plugin.zip sha256sum dist/plugin.zip > dist/plugin.zip.sha256 |
監視とトラブルシューティング
重要なメトリクスと初期対応手順を用意しておきます。アラートは「異常の早期検出」と「誤検知の抑制」の両立を目指します。
推奨監視項目：
- 起動時間（startup latency）
- 処理レイテンシ（p50/p95/p99）
- エラー率（例外発生率）
- メモリ / CPU 使用量
- イベント処理回数
障害発生時の優先チェック（例）：
- ホストログでマニフェストとエントリポイントを確認する
- マニフェスト互換性（min_host_version）を確認する
- 署名・パッケージ形式の不整合を確認する
- 環境変数・シークレットが渡されているか確認する
- 外部APIがタイムアウトしていないかネットワーク疎通を確認する
運用ランブックに上記手順を明記してください。
参考実装・公式リソース
実装や運用に役立つ公式ドキュメントやツールのリンク集を示します。OpenClaw の公式 URL は組織の配布先を確認してください。
- OpenClaw（公式ドキュメント、例）: https://docs.openclaw.example/
- OpenClaw 公式テンプレート（例）: https://github.com/openclaw/plugin-template
- Node.js: https://nodejs.org/
- esbuild: https://esbuild.github.io/
- GitHub Actions ドキュメント: https://docs.github.com/actions
- Dependabot: https://docs.github.com/maintaining-security-updates/keeping-your-dependencies-updated-automatically
- Trivy: https://aquasecurity.github.io/trivy/
- Snyk: https://snyk.io/docs/
- cosign（OCI 署名）: https://docs.sigstore.dev/cosign/
- GPG（署名）: https://gnupg.org/documentation/
- AWS Secrets Manager: https://docs.aws.amazon.com/secretsmanager/
- HashiCorp Vault: https://www.vaultproject.io/
- Prometheus（メトリクス）: https://prometheus.io/docs/introduction/overview/
実際のプロジェクトでは上記ツールの公式ドキュメントを参照して、組織のポリシーに合わせて設定してください。
まとめ
最小プラグインの作成からローカルでの動作確認、テスト、自動化された CI/CD、署名・公開、公開後の監視と脆弱性対応までを、実行可能なコマンドと設定例で示しました。以下の手順を順に実施すると実務で使えるプラグインのワークフローが構築できます。
- 公式 SDK とテンプレートを入手してローカルで動かす
- Node.js（例）で依存を固定し、esbuild でバンドル、zip 化して署名する
- ホストモックで早期に動作確認を行う
- CI にテスト・SCA・ビルド・署名・公開を組み込み、自動化する
- 運用での互換性管理、監視、シークレットローテーションをルール化する
最後に、マニフェストや API シグネチャはプラットフォームの仕様に依存します。実装前に組織やホストの公式リファレンスを必ず参照してください。