Pluginの構築

Plugin は、core を変更せずに OpenClaw を拡張します。Plugin は、メッセージング channel、model provider、local CLI backend、agent tool、hook、media provider、 または別の Plugin 所有の capability を追加できます。

外部 Plugin を OpenClaw リポジトリに追加する必要はありません。package を ClawHub に公開すると、ユーザーは次のコマンドでインストールできます。

openclaw plugins install clawhub:<package-name>

launch cutover の間は、bare package spec も引き続き npm からインストールされます。ClawHub 解決を使いたい場合は、 clawhub: prefix を使用してください。

要件

• Node 22.19+、Node 23.11+、または Node 24+ と、npm や pnpm などの package manager を使用してください。
• TypeScript ESM modules に慣れている必要があります。
• リポジトリ内の bundled plugin 作業では、リポジトリを clone して pnpm install を実行してください。 source-checkout plugin 開発は pnpm のみです。OpenClaw は bundled plugins を extensions/* workspace packages から読み込むためです。

Plugin の形を選ぶ

クイックスタート

必須の agent tool を 1 つ登録して、最小構成の tool plugin を作成します。これは 実用的な Plugin 形態として最短であり、package、manifest、entry point、 local proof を示します。

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

openclaw plugins inspect my-plugin --runtime --json

pnpm test -- extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

openclaw plugins install clawhub:your-org/your-plugin

tools の登録

Tools は required または optional にできます。Required tools は、 Plugin が enabled のとき常に利用できます。Optional tools は user opt-in が必要です。

register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

api.registerTool(...) で登録されたすべての tool は、Plugin manifest でも宣言する必要があります。

{  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

ユーザーは tools.allow で opt in します。

{  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin}

Optional tools は、tool を model に公開するかどうかを制御します。tool または hook が、model に選択された後かつ action 実行前に承認を求めるべき場合は、 plugin permission requests を使用してください。

side effects、一般的でない binaries、または default で公開すべきでない capabilities には optional tools を使用してください。 Tool names は core tools と競合してはいけません。 競合は skipped され、plugin diagnostics で報告されます。parameters のない tool descriptors を含む malformed registrations も skipped され、同じ方法で報告されます。登録済み tools は、policy と allowlist checks を通過した後に model が呼び出せる typed functions です。

Tool factories は runtime-supplied context object を受け取ります。tool が現在の turn の active model を log、display、または adapt する必要がある場合は ctx.activeModel を使用してください。 この object には provider、modelId、modelRef が含まれることがあります。これは informational runtime metadata として扱い、local operator、インストール済み Plugin code、または変更された OpenClaw runtime に対する security boundary として扱わないでください。 Sensitive local tools では引き続き明示的な Plugin または operator opt-in を要求し、 active-model metadata が欠落しているか不適切な場合は fail closed するべきです。

manifest は ownership と discovery を宣言します。execution は引き続き live registered tool implementation を呼び出します。toolMetadata.<tool>.optional: true を api.registerTool(..., { optional: true }) と揃えておくことで、OpenClaw はその Plugin runtime を tool が明示的に allowlisted されるまで読み込まずに済みます。

Import conventions

focused SDK subpaths から import してください。

deprecated root barrel から import しないでください。

Plugin package 内では、internal imports に api.ts や runtime-api.ts などの local barrel files を使用してください。自分の Plugin を SDK path 経由で import しないでください。Provider-specific helpers は、その seam が本当に generic でない限り、 provider package 内に留めてください。

Custom Gateway RPC methods は advanced entry point です。これらは plugin-specific prefix に置いてください。config.*、 exec.approvals.*、operator.admin.*、wizard.*、update.* などの core admin namespaces は reserved のままで、 operator.admin に解決されます。 openclaw/plugin-sdk/gateway-method-runtime bridge は、 contracts.gatewayMethodDispatch: ["authenticated-request"] を宣言する plugin HTTP routes 専用に reserved です。

完全な import map については、Plugin SDK overview を参照してください。

提出前 checklist

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json に正しい openclaw metadata がある OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json manifest が存在し、有効である OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Entry point が defineChannelPluginEntry または definePluginEntry を使用している OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s すべての imports が focused plugin-sdk/<subpath> paths を使用している OPENCLAW_DOCS_MARKER:calloutClose: