コンテンツにスキップ

OpenClawの機能を拡張するプラグイン活用ガイド

開発をしていると、ツールの機能が足りなくて困ることもあれば、逆に機能が多すぎて使いにくいと感じることもあります。自分の環境に合わせて、必要なパーツだけを組み合わせて使えるのが一番ですよね。

OpenClawのプラグインシステムを使えば、必要な機能だけをピンポイントで追加できます。コアシステムを軽量に保ちながら、自分のプロジェクトに最適なツールセットを構築しましょう。

  • OpenClaw 本体
  • Gateway へのアクセス
  • 設定ファイル(plugins.entries)の編集権限

まずは 5 分でプラグインを導入してみましょう。

  1. 現在ロードされているプラグインを確認します。

    Terminal window
    openclaw plugins list
  2. 公式プラグイン(例:Voice Call)をインストールします。

    Terminal window
    openclaw plugins install @openclaw/voice-call
  3. Gateway を再起動し、plugins.entries.<id>.config の項目で設定を行います。

具体的な例については Voice Call のドキュメントも参考にしてください。

OpenClaw では多くの公式プラグインが用意されています。用途に合わせて選択してください。

  • コミュニケーションツール:
    • Microsoft Teams(2026.1.15 以降はプラグイン @openclaw/msteams が必須)
    • Matrix (@openclaw/matrix)
    • Nostr (@openclaw/nostr)
    • Zalo (@openclaw/zalo) / Zalo Personal (@openclaw/zalouser)
  • メモリ・ストレージ:
    • Memory (Core) — 標準のメモリ検索(plugins.slots.memory で有効)
    • Memory (LanceDB) — 長期記憶プラグイン(plugins.slots.memory = "memory-lancedb" で設定)
  • 認証プロバイダー (OAuth):
    • Google Antigravity OAuth (google-antigravity-auth)
    • Gemini CLI OAuth (google-gemini-cli-auth)
    • Qwen OAuth (qwen-portal-auth)
    • Copilot Proxy(VS Code Copilot Proxy ブリッジ)
  • その他:

OpenClaw のプラグインは jiti を介して実行時に読み込まれる TypeScript モジュールです。これらは Gateway と同じプロセスで動作するため、信頼できるコードとして扱ってください。

プラグインを導入することで、以下の機能を追加できます。

  • Gateway RPC メソッドと HTTP ハンドラー
  • Agent ツールと CLI コマンド
  • バックグラウンドサービスと設定バリデーション
  • Skills(マニフェスト内の skills ディレクトリ)と自動応答コマンド

プラグイン内からは api.runtime を通じてコア機能を利用できます。例えば、電話機能で TTS(音声合成)を使うコードは以下の通りです。

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

このヘルパーは messages.tts の設定(OpenAI または ElevenLabs)を使用し、PCM オーディオバッファを返します。

  • 電話機能で音声が出ない: Edge TTS は電話機能(telephony)をサポートしていません。OpenAI または ElevenLabs を設定してください。
  • プラグインのコードがチェックされない: 設定のバリデーション時にはプラグインの実行コードは走りません。代わりにプラグインマニフェストと JSON Schema が使用されます。

不明な点がある場合は AI Setup Assistant で質問してください。

---
title: OpenClawのプラグイン検出と優先順位の仕組み
description: OpenClawがプラグインをスキャンする順番や、複数のプラグインが競合した際の優先ルールについて解説します。
---
プラグインを導入した際、なぜか設定が反映されなかったり、どのファイルが優先されているのか分からなくなったりした経験はありませんか?開発を進める上で、ツールの拡張機能がどのように検出されるかを知っておくことは非常に重要です。
OpenClawでは、明確な優先順位に基づいてプラグインをスキャンします。この仕組みを理解しておけば、意図しない挙動に悩まされることなく、スムーズに開発を進めることができます。
### What You'll Need
- OpenClaw のインストール
- 各プラグインのルートディレクトリに含まれる `openclaw.plugin.json` ファイル
- Node.js 環境(プラグインで npm 依存関係を使用する場合)
### Quick Start
OpenClaw は、以下の順番でプラグインをスキャンします。
1. **Config paths**: `plugins.load.paths`(ファイルまたはディレクトリ)
2. **Workspace extensions**: `<workspace>/.openclaw/extensions/*.ts` または `<workspace>/.openclaw/extensions/*/index.ts`
3. **Global extensions**: `~/.openclaw/extensions/*.ts` または `~/.openclaw/extensions/*/index.ts`
4. **Bundled extensions**: OpenClaw に同梱されているもの(デフォルトでは **disabled**)
Bundled plugins を使用するには、`plugins.entries.<id>.enabled` を設定するか、CLI で `openclaw plugins enable <id>` を実行して明示的に有効化する必要があります。インストールされたプラグインはデフォルトで有効ですが、同じ方法で無効化も可能です。
### Package packs
プラグインのディレクトリに `package.json` を含め、`openclaw.extensions` を定義することで、複数の拡張機能をパッケージとしてまとめることができます。
```json
{
"name": "my-pack",
"openclaw": {
"extensions": ["./src/safety.ts", "./src/tools.ts"]
}
}

この構成では、各エントリが個別のプラグインとなります。プラグイン ID は name/fileBase(例:my-pack/safety)という形式で生成されます。プラグインが npm 依存関係を必要とする場合は、そのディレクトリ内で npm install や pnpm install を実行し、node_modules を利用可能な状態にしてください。

Channel plugins では、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",
"docsLabel": "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"
}
}
}

また、外部のチャンネルカタログ(MPM レジストリのエクスポートなど)を統合することも可能です。以下のいずれかのパスに JSON ファイルを配置してください。

  • ~/.openclaw/mpm/plugins.json
  • ~/.openclaw/mpm/catalog.json
  • ~/.openclaw/plugins/catalog.json

あるいは、環境変数 OPENCLAW_PLUGIN_CATALOG_PATHS(または OPENCLAW_MPM_CATALOG_PATHS)に JSON ファイルのパスをカンマ、セミコロン、または PATH 区切り文字で指定します。各ファイルは { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] } という構造である必要があります。

  • プラグイン ID が重複している: スキャン順序が上位のものが優先され、下位のコピーは無視されます。
  • プラグインが検出されない: パスがファイルを指している場合、そのファイルがあるディレクトリ(プラグインルート)に openclaw.plugin.json マニフェストが存在するか確認してください。

不明な点がある場合は、AI Setup Assistant で詳細を確認できます。

開発を進めていると、特定の機能を追加したり、ツールを自分好みにカスタマイズしたくなる場面がよくあります。しかし、拡張機能の管理が複雑だったり、設定の反映に手間取ったりすると、開発のフローが止まってしまいがちです。
OpenClaw の Plugin システムは、こうした拡張の手間を最小限にするよう設計されています。ID の決まり方や設定ファイルの書き方を理解すれば、すぐに環境を拡張できるようになります。
## 必要なもの
- `openclaw.plugin.json`(Plugin マニフェスト)
- `package.json` またはスタンドアロンの TypeScript ファイル
- OpenClaw CLI がインストールされた環境
## クイックスタート
まずは 5 分で Plugin を使い始めるための最小ステップを紹介します。
1. **Plugin ID を特定する**
`package.json` の `name` フィールド、またはファイル名(`voice-call.ts` なら `voice-call`)が ID になります。
2. **設定ファイル(JSON5)を編集する**
`plugins.entries` に ID を追加して有効化します。
```json
{
plugins: {
enabled: true,
entries: {
"voice-call": { enabled: true, config: { provider: "twilio" } },
},
},
}
  1. CLI でインストールする ローカルのディレクトリを指定してインストールします。

    Terminal window
    openclaw plugins install ./extensions/voice-call
  2. Gateway を再起動する 設定を反映させるために Gateway を再起動してください。


OpenClaw は以下のルールで Plugin ID を決定します。

  • Package packs: package.json の name を使用します。
  • Standalone file: ファイル名から拡張子を除いたものを使用します(例: ~/.../voice-call.ts → voice-call)。

Plugin 側で id を export している場合、OpenClaw はそれを使用しますが、設定された ID と一致しない場合は警告が表示されます。

Plugin の挙動は JSON5 形式の設定ファイルで制御します。

{
plugins: {
enabled: true,
allow: ["voice-call"],
deny: ["untrusted-plugin"],
load: { paths: ["~/Projects/oss/voice-call-extension"] },
entries: {
"voice-call": { enabled: true, config: { provider: "twilio" } },
},
},
}
  • enabled: 全体の有効/無効を切り替えるマスター切替スイッチ(デフォルト: true)
  • allow: 許可リスト(任意)
  • deny: 拒否リスト(任意。allow より優先されます)
  • load.paths: 追加で Plugin を読み込むファイルやディレクトリのパス
  • entries.<id>: Plugin ごとの有効化設定と個別 Config

重要: 設定を変更した後は Gateway の再起動 が必要です。

バリデーションは厳格に行われます。

  • entries, allow, deny, slots に不明な Plugin ID が含まれている場合は エラー になります。
  • channels.<id> に不明なキーがある場合は エラー になります(Plugin マニフェストで宣言されている場合を除く)。
  • Plugin の Config は、openclaw.plugin.json 内の configSchema に基づいて検証されます。
  • Plugin が無効化されている場合、Config は保持されますが 警告 が出力されます。

一部のカテゴリは 排他的 で、一度に 1 つの Plugin しかアクティブにできません。どの Plugin を使用するかは plugins.slots で指定します。

{
plugins: {
slots: {
memory: "memory-core", // memory plugin を無効にする場合は "none" を指定
},
},
}

複数の Plugin が kind: "memory" を宣言している場合、ここで選択されたものだけがロードされます。それ以外は診断情報とともに無効化されます。

Control UI は config.schema(JSON Schema + uiHints)を使用して、使いやすいフォームを表示します。OpenClaw は実行時に以下の情報を uiHints に追加します。

  • plugins.entries.<id> の各項目に Plugin ごとのラベルを付与
  • Plugin から提供された Config フィールドのヒントを plugins.entries.<id>.config.<field> の下にマージ

Plugin の設定画面で適切なラベルやプレースホルダーを表示し、機密情報をマスクしたい場合は、マニフェスト内で uiHints を定義してください。

{
"id": "my-plugin",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"apiKey": { "type": "string" },
"region": { "type": "string" }
}
},
"uiHints": {
"apiKey": { "label": "API Key", "sensitive": true },
"region": { "label": "Region", "placeholder": "us-east-1" }
}
}

Plugin の管理には以下のコマンドを使用します。

Terminal window
openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path> # ローカルのファイル/ディレクトリを ~/.openclaw/extensions/<id> にコピー
openclaw plugins install ./extensions/voice-call # 相対パスも指定可能
openclaw plugins install ./plugin.tgz # ローカルの tarball からインストール
openclaw plugins install ./plugin.zip # ローカルの zip からインストール
openclaw plugins install -l ./extensions/voice-call # 開発用にシンボリックリンクを作成(コピーしない)
openclaw plugins install @openclaw/voice-call # npm からインストール
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

※ plugins update は、plugins.installs で管理されている npm インストールに対してのみ機能します。

Plugin は以下のいずれかの形式で export する必要があります。

  • 関数形式: (api) => { ... }
  • オブジェクト形式: { id, name, configSchema, register(api) { ... } }

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、バイナリ、環境変数、Config などの Hook 適用ルールがそのまま適用されます。
  • Plugin が管理する Hook は、openclaw hooks list で plugin:<id> として表示されます。
  • openclaw hooks コマンドでこれらの Hook を個別に有効/無効にすることはできません。Plugin 自体を有効/無効にしてください。

  • 設定が反映されない: Config の変更後は必ず Gateway を再起動してください。
  • バリデーションエラーが出る: entries や allow リストに、インストールされていない Plugin ID が含まれていないか確認してください。
  • 特定の Plugin がロードされない: plugins.slots を使用するカテゴリ(例: memory)の場合、スロットで正しく選択されているか確認してください。
  • Hook が操作できない: Plugin 管理下の Hook は openclaw hooks からは操作できません。Plugin 側の設定で管理してください。

さらに詳しい情報が必要な場合は、AI Setup Assistant を活用してください。

新しいツールを導入したとき、認証設定のために外部スクリプトを走らせたり、複雑な設定ファイルを何度も書き換えたりするのは手間がかかりますよね。開発者としては、使い慣れた環境の中でスムーズにセットアップを完了させたいものです。

OpenClaw のプラグイン機能を使えば、認証フローや独自のチャネル接続をスマートに統合できます。この記事では、モデルプロバイダーの認証とメッセージングチャネルの作成方法について詳しく見ていきましょう。

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

  • OpenClaw の開発環境
  • 登録するプロバイダーの API 仕様や OAuth の情報
  • メッセージングチャネルの接続先情報(API トークンなど)

まずは、モデルプロバイダーの認証フローを登録する最短ルートを紹介します。

api.registerProvider(...) を使用して、OAuth や API key のセットアップフローを OpenClaw 内部に組み込めます。これにより、ユーザーは外部スクリプトを使わずに認証を完了できるようになります。

api.registerProvider({
id: "acme",
label: "AcmeAI",
auth: [
{
id: "oauth",
label: "OAuth",
kind: "oauth",
run: async (ctx) => {
// OAuth フローを実行し、認証プロファイルを返します。
return {
profiles: [
{
profileId: "acme:default",
credential: {
type: "oauth",
provider: "acme",
access: "...",
refresh: "...",
expires: Date.now() + 3600 * 1000,
},
},
],
defaultModel: "acme/opus-1",
};
},
},
],
});

この設定により、以下の CLI コマンドが利用可能になります。 openclaw models auth login --provider <id> [--method <id>]

実装のポイント:

  • run 関数は ProviderAuthContext を受け取ります。これには prompter, runtime, openUrl, oauth.createVpsAwareHandlers といった便利なヘルパーが含まれています。
  • デフォルトモデルやプロバイダー設定を追加する必要がある場合は、configPatch を返してください。
  • defaultModel を返すと、--set-default フラグによってエージェントのデフォルト設定を更新できます。

2. メッセージングチャネルの作成

Section titled “2. メッセージングチャネルの作成”

WhatsApp や Telegram のようなチャネルを自作することもできます。チャネルの設定は channels.<id> の下に配置され、プラグインコードによって検証されます。

const myChannel = {
id: "acmechat",
meta: {
id: "acmechat",
label: "AcmeChat",
selectionLabel: "AcmeChat (API)",
docsPath: "/channels/acmechat",
blurb: "demo channel plugin.",
aliases: ["acme"],
},
capabilities: { chatTypes: ["direct"] },
config: {
listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
resolveAccount: (cfg, accountId) =>
cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
accountId,
},
},
outbound: {
deliveryMode: "direct",
sendText: async () => ({ ok: true }),
},
};
export default function (api) {
api.registerChannel({ plugin: myChannel });
}

チャネル設定のヒント:

  • 設定値は plugins.entries ではなく、必ず channels.<id> の下に配置してください。
  • meta.label は CLI や UI での表示名として使用されます。
  • meta.aliases を設定すると、CLI 入力時などの ID 正規化に役立ちます。
  • meta.preferOver を使うと、特定のチャネルが既に設定されている場合に自動有効化をスキップさせることができます。

3. ステップバイステップ:新しいチャネルの構築

Section titled “3. ステップバイステップ:新しいチャネルの構築”

モデルプロバイダーではなく、新しい「チャット画面(メッセージングチャネル)」を作りたい場合は、以下の手順で進めてください。

  1. ID と設定形式の決定: 設定は channels.<id> に配置します。複数アカウントをサポートする場合は channels.<id>.accounts.<accountId> の形式が推奨されます。
  2. メタデータの定義: meta.label や meta.docsPath を設定し、UI や CLI での表示を整えます。
  3. 必須アダプターの実装: config.listAccountIds, config.resolveAccount, capabilities, outbound.sendText などを実装します。
  4. オプション機能の追加: 必要に応じて setup (ウィザード) や gateway (起動/停止)、streaming などを追加します。
  5. プラグインの登録: api.registerChannel({ plugin }) を呼び出します。

OpenClaw プラグインでは、認証やチャネル以外にも多様な機能を登録できます。

自動応答コマンド (Auto-reply commands)

Section titled “自動応答コマンド (Auto-reply commands)”

AI エージェントを介さず、スラッシュコマンドで即座にレスポンスを返す機能です。

api.registerCommand({
name: "setmode",
description: "Set plugin mode",
acceptsArgs: true,
requireAuth: true,
handler: async (ctx) => {
const mode = ctx.args?.trim() || "default";
// mode の保存処理など
return { text: `Mode set to: ${mode}` };
},
});

コマンドの仕様:

  • AI エージェントや組み込みコマンドよりも先に処理されます。
  • senderId, channel, isAuthorizedSender, args などのコンテキストを利用できます。
  • コマンド名はケースインセンティブ(大文字小文字を区別しない)です。

Gateway へのメソッド登録や、独自の CLI コマンドも追加可能です。

// Gateway RPC
api.registerGatewayMethod("myplugin.status", ({ respond }) => {
respond(true, { ok: true });
});
// CLI Command
api.registerCli(({ program }) => {
program.command("mycmd").action(() => {
console.log("Hello");
});
}, { commands: ["mycmd"] });

開発中によく遭遇する問題とその解決策です。

  • コマンドが登録できない: help, status, reset などの予約済みコマンド名はプラグインで上書きすることはできません。別の名前を検討してください。
  • 診断エラーが発生する: 複数のプラグインで同じコマンド名を登録しようとするとエラーになります。一意の名前を使用しているか確認してください。
  • 引数が無視される: acceptsArgs: true を設定していない場合、引数が渡されるとコマンドが一致しないと判断され、他のハンドラーへ処理が移ります。
  • 認証エラー: requireAuth が true(デフォルト)の場合、許可された送信者以外からのコマンドは実行されません。

セットアップに関する具体的なアドバイスが必要な場合は、AI Setup Assistant を活用してください。

  • Plugin agent tools: エージェントが使用できるツールの作成方法を学ぶ
  • モデルプロバイダーの詳細なドキュメントは /providers/* を参照してください。
---
title: "OpenClaw プラグイン開発:命名規則と配布のベストプラクティス"
description: "OpenClaw エコシステムにおけるプラグインの命名規則、配布方法、および Voice Call プラグインの実装例について解説します。"
---
開発を進めていると、プラグインの命名や配置場所のルールがバラバラで混乱した経験はありませんか?統一されたルールがないと、プロジェクトが大きくなるにつれてメンテナンスが困難になります。
OpenClaw では、一貫性を保ち、開発者が迷わず拡張機能を構築できるように明確な規約を設けています。これに従うことで、他の開発者があなたのプラグインをスムーズに利用できるようになります。
## 必要なもの
- `openclaw` メインパッケージ
- Node.js 環境
- npm アカウント(プラグインを配布する場合)
## クイックスタート
プラグインを最短で導入・設定するための 4 つのステップです。
1. **命名規則の確認**: Gateway メソッドは `pluginId.action`、Tool は `snake_case` で命名します。
2. **インストール**: `openclaw plugins install <npm-spec>` を実行してプラグインを取得します。
3. **設定の有効化**: `plugins.entries.<id>.enabled` を `true` に設定します。
4. **再起動**: Gateway を再起動して変更を反映させます。
## Naming conventions
プラグインを開発する際は、以下の 4 つの命名規則に従ってください。
- **Gateway methods**: `pluginId.action` 形式を使用します(例: `voicecall.status`)。
- **Tools**: `snake_case` を使用します(例: `voice_call`)。
- **CLI commands**: `kebab-case` または `camelCase` を使用します。
- **注意点**: CLI コマンドを命名する際は、コアコマンドとの衝突を避けてください。
## Skills
プラグインには、リポジトリ内の `skills/<name>/SKILL.md` に Skill を含めることができます。
これを利用するには、`plugins.entries.<id>.enabled` などの設定で有効化し、ワークスペースまたは管理された Skill の場所に配置されていることを確認してください。
## Distribution (npm)
プラグインの推奨されるパッケージ構成は以下の通りです。
- **Main package**: `openclaw`(このリポジトリ)
- **Plugins**: `@openclaw/*` スコープ下の個別 npm パッケージ(例: `@openclaw/voice-call`)
### 公開の規約
プラグインの `package.json` には、1 つ以上のエントリーファイルを含む `openclaw.extensions` フィールドを含める必要があります。エントリーファイルは `.js` または `.ts` が使用可能です(TypeScript は jiti によって実行時にロードされます)。
`openclaw plugins install <npm-spec>` コマンドは `npm pack` を使用し、内容を `~/.openclaw/extensions/<id>/` に展開して設定で有効化します。スコープ付きパッケージの設定キーは、正規化された**スコープなし**の ID が `plugins.entries.*` に使用されます。
## Example plugin: Voice Call
リポジトリに含まれている `voice-call` プラグイン(Twilio またはログ出力)の構成例です。
- **Source**: `extensions/voice-call`
- **Skill**: `skills/voice-call`
- **CLI**: `openclaw voicecall start|status`
- **Tool**: `voice_call`
- **RPC**: `voicecall.start`, `voicecall.status`
### Config 設定例
Twilio を使用する場合:
```json
{
"provider": "twilio",
"twilio": {
"accountSid": "YOUR_SID",
"authToken": "YOUR_TOKEN",
"from": "YOUR_NUMBER"
},
"statusCallbackUrl": "http://example.com/callback",
"twimlUrl": "http://example.com/twiml"
}

開発用(ネットワーク接続なし):

{
"provider": "log"
}

プラグインは Gateway と同じプロセス内で実行されます。以下の 4 つのポイントに注意し、信頼できるコードとして扱ってください。

  • 信頼できるプラグインのみをインストールしてください。
  • plugins.allow による許可リストの使用を推奨します。
  • プラグインの設定変更後は、必ず Gateway を再起動してください。
  • プラグインはプロセス内で直接実行されることを忘れないでください。

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

  • リポジトリ内のプラグイン: src/** 以下に Vitest のテストを配置します(例: src/plugins/voice-call.plugin.test.ts)。
  • 個別に公開されるプラグイン: 独自の CI(lint/build/test)を実行し、openclaw.extensions がビルド済みのエントリーポイント(dist/index.js)を指していることを確認してください。
  • CLI コマンドが動作しない: コアコマンドと名前が衝突していないか確認してください。
  • 変更が反映されない: プラグインのインストールや設定変更の後、Gateway を再起動したか確認してください。

詳細なセットアップと使用方法については、AI Setup Assistant で質問してください。

  • Voice Call の詳細を見る
  • extensions/voice-call/README.md を読む
OpenClaw

OpenClaw Expert

まだ解決しませんか?

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