Plugin の権限リクエスト

Plugin 権限リクエストを使用すると、ユーザーが許可または拒否するまで、Plugin コードがツール呼び出しや Plugin 所有の操作を一時停止できます。これは Gateway の plugin.approval.* フローと、チャットの承認ボタンや /approve コマンドを処理するものと同じ承認 UI サーフェスを使用します。

Plugin/App の権限には、Plugin 権限リクエストを使用してください。これはホストの実行承認、任意ツールの許可リスト、Codex ネイティブの権限レビューに代わるものではありません。

適切なゲートを選択する

必要な判断ポイントに対応するゲートを選択してください。

任意ツールは検出時のゲートです。Plugin 権限リクエストは呼び出しごとのゲートです。機密性の高いツールについて、モデルに表示する前の明示的なオプトインと、アクションの実行前の承認の両方が必要な場合は、両方を使用してください。

ツール呼び出し前に承認をリクエストする

Plugin が作成するプロンプトの多くは、before_tool_call フックから開始する必要があります。このフックは、モデルがツールを選択した後、OpenClaw がそれを実行する前に動作します。

 export default definePluginEntry({  id: "deploy-policy",  name: "Deploy Policy",  register(api) {    api.on("before_tool_call", async (event) => {      if (event.toolName !== "deploy_service") {        return;      }       const environment =        typeof event.params.environment === "string" ? event.params.environment : "unknown";       return {        requireApproval: {          title: "Deploy service",          description: `Deploy service to ${environment}.`,          severity: environment === "production" ? "critical" : "warning",          allowedDecisions:            environment === "production"              ? ["allow-once", "deny"]              : ["allow-once", "allow-always", "deny"],          timeoutMs: 120_000,          onResolution(decision) {            console.log(`deploy approval resolved: ${decision}`);          },        },      };    });  },});

アクションを承認する人に向けてプロンプトのテキストを記述してください。

• title は短く、アクションを明確に示すものにしてください。Gateway では 80 文字に制限されます。
• description は具体的で範囲を限定したものにしてください。Gateway では 512 文字に制限されます。
• アクション、対象、リスクを含めてください。チャットの承認サーフェスに表示すべきでないシークレット、トークン、非公開ペイロードは含めないでください。
• severity を省略した場合のデフォルトは "warning" です。誤った判断によって本番環境の損害やデータ損失が発生する可能性があるアクションに限り、"critical" を使用してください。
• allowedDecisions を省略した場合のデフォルトは ["allow-once", "allow-always", "deny"] です。そのアクションに対する永続的な信頼が安全でない場合は、["allow-once", "deny"] を渡してください。
• timeoutMs のデフォルトは 120000（2 分）で、リクエストされた値にかかわらず上限は 600000（10 分）です。

判断の動作

OpenClaw は plugin: ID を持つ保留中の承認を作成し、利用可能な承認サーフェスに配信して、判断を待ちます。

リクエストで許可された、正確な allow-once と allow-always の判断だけが実行を許可します。不明、不正な形式、不一致、欠落、タイムアウトした判断は、すべて安全側に倒して拒否されます。従来の timeoutBehavior フィールドは Plugin との互換性のため引き続き受け付けられますが、非推奨で無視されます。新しいフックでは設定しないでください。

allow-always が永続化されるのは、リクエスト元の Plugin またはランタイムがその永続化を実装している場合に限られます。通常の before_tool_call.requireApproval フックでは、OpenClaw は allow-once と allow-always を現在の呼び出しに対する承認判断として扱い、解決された値を onResolution に渡します。Plugin で allow-always を提供する場合は、どの将来の呼び出しを信頼するのかを正確に文書化し、実装してください。

フックが params も返す場合、OpenClaw は承認が成功した後にのみ、それらのパラメーター変更を適用します。優先度の高いフックが承認をリクエストした後でも、優先度の低いフックがブロックすることがあります。

allowedDecisions は、ユーザーに表示されるボタンとコマンドを制限します。Gateway は、リクエストで提示されなかった判断による解決の試行を拒否します。

承認プロンプトをルーティングする

承認プロンプトは、ローカル UI サーフェス、または承認処理をサポートするチャットチャネルで解決できます。Plugin 承認プロンプトを明示的なチャット対象に転送するには、approvals.plugin を設定します。

{  approvals: {    plugin: {      enabled: true,      mode: "targets",      agentFilter: ["main"],      targets: [{ channel: "slack", to: "U12345678" }],    },  },}

approvals.plugin は approvals.exec から独立しています。実行承認の転送を有効にしても Plugin 承認プロンプトはルーティングされず、Plugin 承認の転送を有効にしてもホストの実行ポリシーは変更されません。

プロンプトに手動承認用のテキストが含まれている場合は、提示された判断のいずれかで解決してください。

/approve <id> allow-once/approve <id> allow-always/approve <id> deny

転送モデル全体、同一チャット内での承認動作、ネイティブチャネル配信、チャネル固有の承認者ルールについては、高度な実行承認を参照してください。

Codex ネイティブ権限

Codex ネイティブ権限プロンプトも Plugin 承認を介して処理できますが、Plugin が作成するフックとは所有主体が異なります。

• Codex App Server の承認リクエストは、Codex のレビュー後に OpenClaw を介してルーティングされます。
• ネイティブフック permission_request のリレーは、そのリレーが有効な場合、plugin.approval.request を介して確認できます。
• Codex が _meta.codex_approval_kind を "mcp_tool_call" としてマークした場合、MCP ツール承認要請は Plugin 承認を介してルーティングされます。

Codex 固有の動作とフォールバックルールについては、Codex ハーネスランタイムを参照してください。

トラブルシューティング

ツールに Plugin 承認を利用できないと表示される。 リクエストを受け付けた承認 UI または設定済みの承認ルートがありません。承認に対応したクライアントを接続するか、同一チャット内の /approve をサポートするチャネルを使用するか、approvals.plugin を設定してください。

allow-always が表示されるが、次の呼び出しでも再び確認される。 汎用的な Plugin 承認フローでは、任意のフックに対する信頼は自動的に永続化されません。onResolution("allow-always") の後に Plugin 所有の信頼を Plugin 内で永続化するか、allow-once と deny のみを提示してください。

/approve が判断を拒否する。 リクエストによって allowedDecisions が制限されています。プロンプトに表示された判断のいずれかを使用してください。

Discord、Matrix、Slack、または Telegram のプロンプトが実行承認とは異なる方法でルーティングされる。 Plugin 承認と実行承認は別々の設定を使用し、異なる認可チェックを使用する場合があります。approvals.exec だけを確認するのではなく、approvals.plugin と、そのチャネルの Plugin 承認サポートを確認してください。

関連項目

• Plugin フック
• Plugin の構築
• 高度な実行承認
• Gateway プロトコル
• Codex ハーネスランタイム