OpenClaw Pluginsで機能を拡張する

開発を進めていると、「コア機能にはないけれど、どうしてもこの特定の機能が欲しい」という場面があります。しかし、メインのコードベースを直接書き換えるのは、メンテナンスやアップデートの面でも避けたいところです。

そんな時に役立つのがプラグインです。プラグインは、本体のコードに触れることなく、コマンドやツール、チャンネル、さらには統合フロー全体を追加できる小さなコードモジュールです。私は音声通話からカスタムのSlack連携まで、あらゆる場面でプラグインを使っています。パターンさえ理解してしまえば、驚くほど簡単に作成できます。

必要なもの

OpenClawがインストールされ、実行されていること
TypeScriptの基礎知識（カスタムプラグイン作成時）

Quick Start (3分)

ステップ 1: ロードされているプラグインを確認する

現在どのようなプラグインが認識されているかを確認します。

openclaw plugins list

ステップ 2: 公式プラグインをインストールする

例として、音声通話プラグインをインストールします。

openclaw plugins install @openclaw/voice-call

ステップ 3: 再起動と設定

Gatewayを再起動した後、設定ファイルの plugins.entries.<id>.config に設定を追加します。

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio"
        }
      }
    }
  }
}

これで完了です。新しいプラグインが使えるようになりました。

Official Plugins

現在、以下の公式プラグインが利用可能です。

プラグイン	パッケージ	説明
Voice Call	`@openclaw/voice-call`	電話の発着信
Microsoft Teams	`@openclaw/msteams`	Teamsチャンネル連携
Matrix	`@openclaw/matrix`	Matrixチャットプロトコル
Nostr	`@openclaw/nostr`	Nostr分散型チャット
Zalo	`@openclaw/zalo`	ベトナムのメッセージングアプリ

同梱プラグイン（デフォルトでは無効になっています）:

Memory (Core) — 基本的なメモリ検索
Memory (LanceDB) — 自動呼び出し機能付きの長期メモリ
Google/Gemini/Qwen OAuth — プロバイダー認証フロー

同梱プラグインを有効にするには、以下のコマンドを実行します。

openclaw plugins enable memory-lancedb

Plugin Discovery

OpenClawは以下の順序でプラグインをスキャンします。

Config paths — plugins.load.paths で指定されたパス
Workspace extensions — .openclaw/extensions/*.ts
Global extensions — ~/.openclaw/extensions/*.ts
Bundled — OpenClawに標準で含まれるもの

最初に一致したものが優先され、それ以降に発見された同じIDのコピーは無視されます。

Configuration

詳細な設定は以下のように記述します。

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],           // 許可リスト（オプション）
    deny: ["untrusted-plugin"],      // 拒否リストが優先されます
    load: {
      paths: ["~/my-plugins/custom"]
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" }
      }
    }
  }
}

設定を変更した後は、必ず Gateway の再起動を行ってください。

Plugin Slots (排他的なカテゴリ)

メモリプロバイダーなどの特定のカテゴリでは、一度に1つのプラグインだけがアクティブになるよう制限されています。

{
  plugins: {
    slots: {
      memory: "memory-lancedb"  // または "memory-core" か "none"
    }
  }
}

CLI Commands

プラグインの管理には以下のコマンドを使用します。

openclaw plugins list                    # すべてのプラグインを表示
openclaw plugins info \<id\>               # プラグインの詳細を確認
openclaw plugins install &lt;path|npm&gt;      # プラグインをインストール
openclaw plugins install -l \<path\>       # 開発用にリンクを作成
openclaw plugins enable \<id\>             # プラグインを有効化
openclaw plugins disable \<id\>            # プラグインを無効化
openclaw plugins update \<id\>             # npmプラグインを更新
openclaw plugins update --all            # すべてのnpmプラグインを更新
openclaw plugins doctor                  # 問題を診断

トラブルシューティング

プラグインが正しく読み込まれない場合や、動作に問題がある場合は、組み込みの診断ツールを使用してください。

問題の診断: openclaw plugins doctor を実行します。システムがプラグインの状態をチェックし、異常があれば報告します。

解決しない場合や、セットアップに関する具体的な質問がある場合は、AI Setup Assistant に相談してください。

次のステップ

開発をしていると、既存のツールではどうしても手が届かない痒い部分が出てくるものです。「あと少しだけこの機能がこう動けばいいのに」と思いながら、結局ワークフローをツールに合わせて調整した経験はありませんか？

OpenClaw の Plugin システムを使えば、そんな悩みは解決します。自分専用のロジックを組み込んで、ツールを自分の仕事のやり方に合わせることができます。

## 必要なもの

作業を始める前に、以下の準備ができているか確認してください。

- `~/.openclaw/extensions/` ディレクトリへのアクセス権
- OpenClaw の動作環境

## クイックスタート

まずは 5 分で最小構成の Plugin を動かしてみましょう。

1. `~/.openclaw/extensions/my-plugin/index.ts` を作成し、以下のコードを記述します。

```ts
export default function(api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { status: "running" });
  });
}

同じディレクトリに ~/.openclaw/extensions/my-plugin/openclaw.plugin.json を作成します。

{
  "id": "my-plugin",
  "name": "My Custom Plugin",
  "version": "1.0.0"
}

Gateway を再起動すれば、あなたの Plugin が有効になります。

便利な機能の追加

最小構成が動いたら、次はより具体的な機能を追加してみましょう。

Tool の登録

AI が呼び出せる Tool を登録するには、api.registerTool を使用します。

export default function(api) {
  api.registerTool({
    name: "my_tool",
    description: "Does something useful",
    parameters: {
      type: "object",
      properties: {
        input: { type: "string" }
      }
    },
    handler: async ({ input }) => {
      return { result: `Processed: ${input}` };
    }
  });
}

Slash Command の登録

AI を介さずに素早くコマンドを実行したい場合は、Slash Command が最適です。ステータス確認や簡単な切り替え操作に便利です。

export default function(api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin running on ${ctx.channel}`
    })
  });
}

Channel の登録

独自のメッセージングサービスを統合することもできます。

const plugin = {
  id: "acmechat",
  meta: {
    label: "AcmeChat",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging."
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) =>
      Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, id) =>
      cfg.channels?.acmechat?.accounts?.[id ?? "default"]
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // Send message
      return { ok: true };
    }
  }
};

export default function(api) {
  api.registerChannel({ plugin });
}

Plugin Hooks

Plugin に Hook を同梱して、実行時に登録することができます。これにより、別の Hook パックをインストールすることなく、イベント駆動の自動化を Plugin だけで完結できます。

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

知っておくべきこと:

Hook ディレクトリの構造は、通常の Hook 形式（HOOK.md + handler.ts）に従う必要があります。
OS、バイナリ、環境変数、設定などの Hook 適用ルールは通常通り適用されます。
Plugin によって管理される Hook は、openclaw hooks list で plugin:<id> として表示されます。
Plugin 自体の有効化・無効化で、その Hook も制御できます。

Runtime Helpers

api.runtime を通じて、OpenClaw コアのヘルパーにアクセスできます。例えば、電話用の TTS（音声合成）を利用する場合は以下のようになります。

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

知っておくべきこと:

コアの messages.tts 設定（OpenAI または ElevenLabs）を使用します。
PCM オーディオバッファとサンプルレートを返します。
プロバイダーに合わせて、Plugin 側でリサンプリングやエンコードを行う必要があります。
Edge TTS は電話機能（telephony）ではサポートされていません。

Provider Plugins (Model Auth)

OAuth や API キーの設定フローを OpenClaw 内部で実行できるように、モデルプロバイダーの認証フローを登録できます。

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // Run OAuth flow and return auth profiles
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

知っておくべきこと:

run 関数は、prompter, runtime, openUrl ヘルパーを含む ProviderAuthContext を受け取ります。
デフォルトモデルを追加する必要がある場合は configPatch を返してください。
defaultModel を返すと、--set-default を使用してエージェントのデフォルトを更新できます。

ユーザーは以下の CLI コマンドで認証を実行します。

openclaw models auth login --provider acme --method oauth

トラブルシューティング

Hook が表示されない: openclaw hooks list を実行して、plugin:<id> の形式でリストに含まれているか確認してください。また、OS や環境変数の要件を満たしているか再確認が必要です。
電話機能で音声が出ない: Runtime Helpers を使用する場合、Edge TTS はサポートされていません。OpenAI または ElevenLabs が設定されているか確認してください。
認証フローが失敗する: api.registerProvider の run 関数内で適切な credential オブジェクトが返されているか確認してください。

セットアップで困ったときは、AI Setup Assistant に相談してみてください。

次のステップ

Channel の詳細設定
Plugin SDK リファレンス

AI エージェントは非常に強力ですが、すべてのリクエストを AI に処理させる必要はありません。例えば、現在のステータス確認や定型文の返信など、決まった動作を高速に実行したい場面があります。AI の応答を待つまでもない単純なタスクには、Auto-Reply Commands を使うのが最適です。

この機能を使えば、AI エージェントを呼び出さずに、特定のロジックを直接実行するスラッシュコマンドをプラグインから提供できます。

必要なもの

OpenClaw プラグインの開発環境
openclaw.plugin.json（Plugin Manifest）
TypeScript の基本知識

クイックスタート

プラグインでカスタムスラッシュコマンドを登録するには、api.registerCommand を使用します。以下のコードは、現在のチャンネル情報を返す単純なコマンドの例です。

export default function(api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    acceptsArgs: false,
    requireAuth: true,
    handler: (ctx) => ({
      text: `Plugin running on ${ctx.channel}`
    })
  });
}

Command Context

handler 関数に渡される ctx オブジェクトには、以下のフィールドが含まれます。

フィールド	説明
`senderId`	送信者の ID
`channel`	コマンドが送信されたチャンネル
`isAuthorizedSender`	送信者が承認済みかどうか
`args`	引数（`acceptsArgs: true` の場合）
`commandBody`	コマンドの全文
`config`	現在の OpenClaw の設定

Command Options

コマンドを登録する際のオプションは以下の通りです。

オプション	説明
`name`	コマンド名（`/` は含めない）
`description`	ヘルプテキスト
`acceptsArgs`	引数を受け取るかどうか（デフォルト: false）
`requireAuth`	承認された送信者を必須とするか（デフォルト: true）
`handler`	`{ text: string }` を返す関数

バックグラウンドサービスの登録

コマンドだけでなく、プラグインの起動・停止に合わせて動作するサービスも登録可能です。

export default function(api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

CLI コマンドの登録

ターミナルから実行する CLI コマンドを追加する場合は、api.registerCli を使用します。

export default function(api) {
  api.registerCli(({ program }) => {
    program.command("mycmd").action(() => {
      console.log("Hello");
    });
  }, { commands: ["mycmd"] });
}

Plugin Manifest

すべてのプラグインには openclaw.plugin.json が必要です。ここでプラグインの ID や設定のスキーマを定義します。

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true }
  }
}

Publishing to npm

作成したプラグインを公開して利用可能にする手順は以下の通りです。

package.json に OpenClaw 用の設定を追記します。

{
  "name": "@yourscope/my-plugin",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

npm に公開します。

npm publish

利用者は以下のコマンドでインストールできます。

openclaw plugins install @yourscope/my-plugin

トラブルシューティング

優先順位: プラグインコマンドは、組み込みコマンドや AI エージェントよりも先に処理されます。
大文字・小文字: コマンド名はケースインセンティブ（大文字・小文字を区別しない）です。
予約済みコマンド: help, status, reset はシステムで予約されているため、上書きできません。

さらに詳しい設定やトラブルシューティングが必要な場合は、AI Setup Assistant を活用してください。

次のステップ

---
title: OpenClaw プラグインのトラブルシューティングと高度な設定ガイド
description: プラグインが読み込まれない問題の解決方法から、Package Packs や Channel Metadata の詳細な設定手順までを解説します。
---

新しい機能を拡張しようとして、プラグインが期待通りに動かないと困ってしまいますよね。「設定ファイルは書いたはずなのに、なぜか反映されない……」といった状況は、開発を進める上で誰もが一度は直面する悩みです。

この記事では、OpenClaw でプラグインを扱う際によくあるトラブルの解決策と、複数のプラグインを効率よく管理するためのベストプラクティスを紹介します。

## 必要なもの

作業を始める前に、以下の準備ができているか確認してください。

- OpenClaw のインストール環境
- `package.json` または `openclaw.plugin.json` を含むプラグインディレクトリ
- Node.js および npm
- 編集権限のある設定ファイル

## クイックスタート

まずは最小限の構成でプラグインを動作させるための 2 つのステップを確認しましょう。

### 1. Package Packs の設定
プラグインディレクトリ内の `package.json` に `openclaw.extensions` を定義します。これにより、1 つのディレクトリで複数のプラグインを管理できます。

```json
{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

2. 依存関係のインストール

プラグインが npm パッケージに依存している場合は、そのディレクトリ内でインストールを実行してください。

cd ~/.openclaw/extensions/my-pack
npm install

トラブルシューティング

プラグインがうまく動作しない場合は、以下の 4 つのポイントを確認することをおすすめします。

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

以下の項目を順番にチェックしてください。

plugins.enabled が true に設定されていますか？
そのプラグインが deny リストに入っていませんか？
ディレクトリ内に openclaw.plugin.json が存在していますか？

2. 設定のバリデーションエラー

設定ファイル内に、不明なプラグイン ID が含まれていると厳格なエラーが発生します。 修正方法: entries、allow、deny の項目から、無効化されたプラグインやアンインストール済みのプラグインへの参照を削除してください。

3. プラグインの競合

同じ ID を持つプラグインが複数存在する場合、最初に検出されたプラグインのみが読み込まれます。 修正方法: extension ディレクトリから重複しているプラグインを削除してください。

4. カタログメタデータの配置

外部カタログが認識されない場合は、以下の正しいパスに JSON ファイルが配置されているか確認してください。

~/.openclaw/mpm/plugins.json
~/.openclaw/mpm/catalog.json
~/.openclaw/plugins/catalog.json または、環境変数 OPENCLAW_PLUGIN_CATALOG_PATHS を設定する方法も有効です。

Channel Catalog Metadata

Channel プラグインでは、openclaw.channel を使用してオンボーディング用のメタデータを、openclaw.install を使用してインストール時のヒントを提供できます。

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

もしパック内に複数の拡張機能が含まれている場合、プラグイン ID は name/<fileBase> という形式（例: my-pack/safety）になります。

解決しない問題がある場合は、私たちの AI Setup Assistant がプラグインセットアップのデバッグをお手伝いします。

次のステップ

新しいプラットフォームが登場するたびに、既存のツールをどう接続するか悩むのは開発者共通の悩みです。特定のチャットツールを使いたいのに、標準でサポートされていないと、結局自分でコードを書くしかありません。

モデルプロバイダーではなく、**新しいチャット画面（chat surface）**を追加したい場合は、以下の手順で Messaging Channel を作成してください。

## 必要なもの
- OpenClaw Gateway 環境
- TypeScript / Node.js
- npm (テスト実行用)

## Quick Start: 5分で始めるチャネル作成

### Step 1: ID と Config の形状を決める
すべてのチャネル設定は `channels.<id>` の下に配置します。まずは設定ファイルの構造を定義しましょう。

```json
{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "TOKEN", enabled: true }
      }
    }
  }
}

Step 2: Channel Metadata を定義する

CLI や UI でどのように表示されるかを設定します。

フィールド	用途
`meta.label`	CLI/UI での表示名
`meta.selectionLabel`	選択時の長い説明テキスト
`meta.docsPath`	ドキュメントへのリンク (例: `/channels/acmechat`)
`meta.blurb`	短い説明文
`meta.aliases`	代替チャネル ID
`meta.preferOver`	他のチャネルを置き換える設定

Step 3: Required Adapters を実装する

チャネルの核となる動作を実装します。listAccountIds、resolveAccount、そしてメッセージ送信用の sendText が必須です。

const plugin = {
  id: "acmechat",
  meta: { /* ... */ },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, id) => cfg.channels?.acmechat?.accounts?.[id ?? "default"]
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => ({ ok: true })
  }
};

Step 4: Optional Adapters を追加する

必要に応じて、以下の機能を追加してチャネルをリッチにできます。

Adapter	用途
`setup`	ウィザード形式のセットアップ
`security`	DM ポリシーの設定
`status`	ヘルスチェックと診断
`gateway`	開始/停止/ログイン処理
`mentions`	@メンションの処理
`threading`	スレッド対応
`streaming`	ストリーミングレスポンス
`actions`	メッセージアクション
`commands`	ネイティブコマンドの動作

Step 5: Register

最後に、API を使用してチャネルを登録します。

export default function(api) {
  api.registerChannel({ plugin });
}

Naming Conventions

命名規則に従うことで、他のコンポーネントとの衝突を防げます。

タイプ	規則	例
Gateway メソッド	`pluginId.action`	`voicecall.status`
Tools	`snake_case`	`voice_call`
CLI コマンド	kebab-case	`voicecall-start`

コアコマンドと名前が重ならないように注意してください。

Skills in Plugins

プラグインに skills/ ディレクトリを含めることで、スキルを同梱できます。

my-plugin/
├── index.ts
├── openclaw.plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

plugins.entries.<id>.enabled を設定し、管理対象のスキルパスに存在することを確認してください。

Safety Notes

プラグインは Gateway と**同一プロセス内（in-process）**で動作します。信頼できるコードとして扱ってください。

信頼できるプラグインのみをインストールしてください。
plugins.allow による許可リストの使用を推奨します。
設定変更後は Gateway を再起動してください。
有効化する前にプラグインのソースコードを確認してください。

Testing Plugins

作成したプラグインにはテストを含めるべきです。

リポジトリ内プラグイン: Vitest テストを src/** 以下に配置します（例: src/plugins/voice-call.plugin.test.ts）。
公開済みプラグイン: 独自の CI を実行し、openclaw.extensions がビルド済みのエントリポイントを指しているか確認してください。

# プラグインのテストを実行
cd ~/.openclaw/extensions/my-plugin
npm test

トラブルシューティング

コマンドの衝突: プラグインのコマンド名が OpenClaw のコアコマンドと重複していないか確認してください。
変更が反映されない: プラグインや設定を変更した後は、必ず Gateway を再起動してください。

AI Setup Assistant

次のステップ

Plugin Agent Tools → — AI から呼び出し可能なツールを構築する
Plugin Manifest → — マニフェストの完全なリファレンス
Voice Call Plugin → — サンプルプラグインの実装例

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。