OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin SDK reference

エージェントハーネスのプラグイン

エージェントハーネスは、準備済みの OpenClaw エージェントによる1回のターンを実行する低レベルの実行機構です。モデルプロバイダーでも、チャネルでも、ツールレジストリでもありません。ユーザー向けの概念モデルについては、エージェントランタイムを参照してください。

このサーフェスは、同梱または信頼済みのネイティブ Plugin にのみ使用してください。パラメーター型が意図的に現在の組み込みランナーを反映しているため、このコントラクトはまだ実験的です。

ハーネスを使用する場合

モデルファミリーが独自のネイティブセッションランタイムを持ち、通常の OpenClaw プロバイダー転送が適切な抽象化ではない場合に、エージェントハーネスを登録します。

  • スレッドと Compaction を所有するネイティブのコーディングエージェントサーバー
  • ネイティブの計画、推論、ツールイベントをストリーミングする必要があるローカル CLI またはデーモン
  • OpenClaw セッショントランスクリプトに加えて、独自の再開 ID を必要とするモデルランタイム

新しい LLM API を追加するためだけにハーネスを登録してはなりません。通常の HTTP または WebSocket モデル API には、プロバイダー Pluginを構築してください。

コアが引き続き所有するもの

ハーネスが選択される前に、OpenClaw はすでに以下を解決しています。

  • プロバイダーとモデル
  • ランタイム認証状態（ハーネスが認証ブートストラップを所有すると宣言している場合を除く）
  • 思考レベルとコンテキスト予算
  • OpenClaw のトランスクリプト／セッションファイル
  • ワークスペース、サンドボックス、ツールポリシー
  • チャネル応答コールバックとストリーミングコールバック
  • モデルのフォールバックと実行中のモデル切り替えポリシー

ハーネスは準備済みの試行を実行します。プロバイダーを選択したり、チャネル配信を置き換えたり、暗黙にモデルを切り替えたりはしません。

ハーネス所有の認証ブートストラップ

デフォルトでは、コアがハーネスを呼び出す前にプロバイダー認証情報を解決します。独自のネイティブランタイムを通じて認証できる信頼済みハーネスは、静的な AgentHarness 登録で authBootstrap: "harness" を設定できます。この場合、コアはそのハーネスが引き受けるすべての試行について、汎用のプロバイダー認証情報ブートストラップと認証情報不足エラーを省略します。

互換性があり、明示的に選択または順序付けされた OpenClaw 認証プロファイルと、そのスコープ付きストアが存在する場合、コアは引き続きそれらを転送します。ハーネスはモデルリクエストを発行する前に、そのプロファイルまたはネイティブ認証情報を解決し、シークレットを試行のスコープ内に保ち、対処可能な認証エラーを提示する必要があります。認証を一部の場合にしか所有しないハーネスには、このケイパビリティを設定しないでください。

検証済みセットアップランタイムアーティファクト

初回セットアップに推論機能を提供できるローカルハーネスは、プローブを完了した実装を証明する必要があります。params.captureRuntimeArtifact が true の場合、安定した ID とコンテンツフィンガープリントを持つ不透明な result.runtimeArtifact を返してください。別のハーネスをロードしたり、無関係な Plugin をスキャンしたりせずに、その結び付きを再確認する、一致する runtimeArtifact.validate(...) ケイパビリティを登録してください。

検証済みの OpenClaw 継続処理では、params.expectedRuntimeArtifact も渡されます。ハーネスは、取得した正確なネイティブプロセスとそれを比較し、異なる場合はネイティブスレッドを開始または再開する前に失敗しなければなりません。通常のエージェントターンでは両方のフィールドが省略されるため、コンテンツハッシュは通常のリクエストのホットパスに入りません。リモート／WebSocket ハーネスが参加するには、サーバー証明コントラクトが必要です。バージョン文字列だけではアーティファクトの識別情報になりません。

準備済みの試行には、OpenClaw とネイティブハーネスの間で共有し続ける必要があるランタイム判断のために、OpenClaw が所有するポリシーバンドル params.runtimePlan も含まれます。

  • プロバイダー対応のツールスキーマポリシー用の runtimePlan.tools.normalize(...) と runtimePlan.tools.logDiagnostics(...)
  • トランスクリプトのサニタイズとツール呼び出し修復ポリシー用の runtimePlan.transcript.resolvePolicy(...)
  • 共有 NO_REPLY とメディア配信抑制用の runtimePlan.delivery.isSilentPayload(...)
  • モデルフォールバック分類用の runtimePlan.outcome.classifyRunResult(...)
  • 解決済みのプロバイダー／モデル／ハーネスメタデータ用の runtimePlan.observability

ハーネスは、OpenClaw の動作と一致させる必要がある判断にこのプランを使用できますが、ホストが所有する試行状態として扱ってください。変更したり、ターン内でプロバイダー／モデルを切り替えるために使用したりしないでください。

リクエスト転送コントラクト

supports(ctx) は、解決済みのモデル転送を ctx.modelProvider で受け取ります。シークレットを含まない、プロバイダー所有の2つの情報が、選択されたルートを説明します。

  • runtimePolicy.compatibleIds は、その具体的なルートと互換性があるとプロバイダーが宣言しているランタイム ID を列挙します。ポリシーが存在しない場合、プロバイダーがルートレベルの互換性を宣言していないことを意味します。サポートを仮定する許可ではありません。
  • requestTransportOverrides: "none" は、作成者が指定したプロバイダー／モデルのリクエストオーバーライドを再現する必要がないことを意味します。"present" は、作成者が指定したヘッダー、認証転送、プロキシ、TLS、ローカルサービス、プライベートネットワーク動作、またはリクエストパラメーターが存在することを意味します。この情報によってそれらの値が公開されることはありません。

ハーネスが準備済みの転送を再現できない場合は、{ supported: false, reason } を返してください。選択後に生の設定を読み取ってサポートを推測しないでください。認証の準備によって複数の再試行ルートが生成される場合、ディスパッチ前に1つのハーネスがそのすべてをサポートする必要があります。暗黙的選択では、完全なセットを所有できる Plugin がない場合は OpenClaw を使用します。明示的または永続化された Plugin 選択では、フェイルクローズします。

ハーネスを登録する

インポート: openclaw/plugin-sdk/agent-harness

typescript
  const myHarness: AgentHarness = {  id: "my-harness",  label: "My native agent harness",   supports(ctx) {    const routeSupportsHarness =      ctx.modelProvider?.runtimePolicy?.compatibleIds.includes("my-harness") === true;    const canReproduceRequest = ctx.modelProvider?.requestTransportOverrides !== "present";    return ctx.provider === "my-provider" && routeSupportsHarness && canReproduceRequest      ? { supported: true, priority: 100 }      : { supported: false, reason: "effective route is not harness-compatible" };  },   async runAttempt(params) {    // ネイティブスレッドを開始または再開します。    // params.prompt、params.tools、params.images、params.onPartialReply、    // params.onAgentEvent、およびその他の準備済み試行フィールドを使用します。    return await runMyNativeTurn(params);  },}; export default definePluginEntry({  id: "my-native-agent",  name: "My Native Agent",  description: "選択したモデルをネイティブエージェントデーモン経由で実行します。",  register(api) {    api.registerAgentHarness(myHarness);  },});

authBootstrap は、この汎用的な例では意図的に省略されています。ハーネスが上記のコントラクトを満たす場合にのみ authBootstrap: "harness" を追加してください。

委任実行

ハーネス所有者は、Codex を基盤とする会話を継続する音声転送など、モデルが固定された既存セッションを実行する必要がある信頼済み Plugin の ID を delegatedExecutionPluginIds に設定できます。これは所有者による静的な同意であり、コアの許可リストではありません。対象を限定してください。

委任先には、作業の受け入れと組み込み実行のみが付与されます。OpenClaw は、保存されている正確なセッションキー、ストアパス、セッション ID、modelSelectionLocked: true、および一致する agentHarnessId と agentHarnessRuntimeOverride の値を要求します。その後、実行はハーネス所有者を通じてスコープ設定されます。セッションの作成、パッチ適用、リセット、削除、アーカイブ、および Gateway の変更は、引き続き所有者のみに許可されます。

選択ポリシー

OpenClaw は、プロバイダー／モデルの解決後にハーネスを選択します。

  1. モデルスコープのランタイムポリシーが優先されます。
  2. 次に、プロバイダースコープのランタイムポリシーが適用されます。
  3. auto は、解決済みの有効なルートをサポートしているかどうかを、登録済みハーネスに問い合わせます。プロバイダー／モデルのプレフィックスだけでハーネスが選択されることはありません。
  4. 一致する登録済みハーネスがない場合、OpenClaw は組み込みランタイムを使用します。

Plugin ハーネスの障害は、実行失敗として提示されます。auto モードでは、解決済みのプロバイダー／モデルをサポートする登録済み Plugin ハーネスがない場合にのみ、組み込みへのフォールバックが適用されます。Plugin ハーネスが実行を引き受けた後、OpenClaw は同じターンを別のランタイムで再実行しません。認証／ランタイムのセマンティクスが変わったり、副作用が重複したりする可能性があるためです。

設定済みのランタイムポリシーは、望ましいランタイムに関する権威ある情報であり続けます。永続化されたセッションの agentHarnessId は、ルート／認証の準備がまだ保留中でも、そのネイティブトランスクリプトの所有権を維持します。どちらも互換性のないルートを互換にするものではありません。準備済みの情報が存在するようになった時点で、選択または固定されたハーネスがそれらをサポートしなければ、実行はフェイルクローズします。/status は、ポリシー、永続化された所有権、ルートサポートから選択された有効なランタイムを表示します。 準備状態は明示的です。欠落している runtimePolicy は、たまたま存在する転送フィールドから推測されず、未宣言のままになります。 ハーネス所有の認証によって複数の物理ルートが未解決のままになる場合、準備済みサポート情報はそれらの互換ランタイム ID の積集合となり、いずれかの候補にリクエストオーバーライドがある場合はそれを報告します。したがって、未宣言の候補が1つでもあると、ネイティブ互換性は空になります。preparedAuth.source: "harness" は認証所有者であり、ルートサポートを推測する許可ではありません。

選択されたハーネスが想定外の場合は、agents/harness デバッグログを有効にし、Gateway の構造化された agent harness selected レコードを確認してください。これには、選択されたハーネス ID、選択理由、ランタイム／フォールバックポリシー、および auto モードでは各 Plugin 候補のサポート結果が含まれます。

同梱の Codex Plugin は、そのハーネス ID として codex を登録します。コアはこれを通常の Plugin ハーネス ID として扱います。Codex 固有のエイリアスは、共有ランタイムセレクターではなく、Plugin またはオペレーター設定に属します。

プロバイダーとハーネスの組み合わせ

ほとんどのハーネスでは、プロバイダーも登録する必要があります。プロバイダーによって、モデル参照、認証状態、モデルメタデータ、および /model の選択が OpenClaw の他の部分から認識可能になります。その後、ハーネスが supports(...) でそのプロバイダーを引き受けます。

同梱の Codex Plugin は、このパターンに従います。

  • 推奨されるユーザーモデル参照: openai/gpt-5.6-sol
  • 互換性参照: 従来の codex/gpt-* 参照は引き続き受け入れられますが、新しい設定では通常のプロバイダー／モデル参照として使用しないでください
  • ハーネス ID: codex
  • 認証: Codex ハーネスがネイティブ Codex ログイン／セッションを所有するため、合成プロバイダー可用性を使用
  • アプリサーバーリクエスト: OpenClaw はモデル ID のみを Codex に送信し、ハーネスがネイティブのアプリサーバープロトコルと通信します

Codex Plugin は追加的です。ランタイムポリシーが未設定または auto の場合、OpenAI が Codex を選択できるのは、そのプロバイダー所有のルートコントラクトが codex に互換性があると宣言している場合のみです。つまり、作成者が指定したリクエストオーバーライドのない、正確な公式 HTTPS Platform Responses または ChatGPT Responses ルートです。openai/* プレフィックスだけで Codex が選択されることはありません。カスタムエンドポイント、Completions アダプター、および作成者が指定したリクエスト動作は OpenClaw 上に留まります。公式の平文 HTTP エンドポイントは拒否されます。古い codex/gpt-* 参照は引き続き互換性入力として扱われます。OpenAI の暗黙的エージェントランタイムを参照してください。

オペレーター向けセットアップ、モデルプレフィックスの例、および Codex 専用設定については、Codex ハーネスを参照してください。

Codex Plugin は、Codex ハーネスに記載されているアプリサーバーの最低バージョンを適用します。初期化ハンドシェイクを確認し、古いサーバーまたはバージョン情報のないサーバーをブロックするため、OpenClaw はテスト済みのプロトコルサーフェスに対してのみ実行されます。

ツール結果ミドルウェア

同梱 Plugin、および一致するマニフェストコントラクトを持つ明示的に有効化されたインストール済み Plugin は、マニフェストの contracts.agentToolResultMiddleware で対象のランタイム ID を宣言している場合、api.registerAgentToolResultMiddleware(...) を通じてランタイムに依存しないツール結果ミドルウェアを接続できます。この信頼済みの接続面は、OpenClaw または Codex がツール出力をモデルに戻す前に実行する必要がある、非同期のツール結果変換のためのものです。

従来のバンドル Plugin は、Codex app-server 専用ミドルウェアに api.registerCodexAppServerExtensionFactory(...) を引き続き使用できますが、新しい結果変換ではランタイム中立 API を使用する必要があります。embedded runner 専用の api.registerEmbeddedExtensionFactory(...) フックは削除されました。埋め込みツール結果の変換では、ランタイム中立ミドルウェアを使用する必要があります。

ターミナル結果の分類

独自のプロトコル投影を所有するネイティブハーネスは、完了したターンで表示可能なアシスタントテキストが生成されなかった場合、 openclaw/plugin-sdk/agent-harness-runtime の classifyAgentHarnessTerminalOutcome(...) を使用できます。このヘルパーは empty、reasoning-only、または planning-only を返し、OpenClaw のフォールバックポリシーが別のモデルで再試行するかどうかを判断できるようにします。planning-only にはハーネスの明示的な planText フィールドが必要です。OpenClaw はアシスタントの文章からこれを推測しません。このヘルパーは意図的に、プロンプトエラー、進行中のターン、および NO_REPLY などの意図的な無言の応答を分類しません。

エージェント終了時の副作用

ネイティブハーネスは試行を確定した後、 openclaw/plugin-sdk/agent-harness-runtime の runAgentEndSideEffects(...) を呼び出す必要があります。これは、対話型応答を遅延させることなく、移植可能な agent_end フックと OpenClaw のリサーチキャプチャをディスパッチします。これらの副作用が完了するまで試行を解決してはならないローカルの非対話型実行では、awaitAgentEndSideEffects(...) を使用します。どちらのヘルパーも runAgentHarnessAgentEndHook(...) と同じ { event, ctx } ペイロードを受け取ります。これらの失敗によって、完了した試行結果が変更されることはありません。

ユーザー入力とツールサーフェス

ランタイムレベルのユーザー入力要求を公開するネイティブハーネスは、 openclaw/plugin-sdk/agent-harness-runtime のユーザー入力ヘルパーを使用してプロンプトを整形し、OpenClaw のブロッキング応答パスを通じて配信し、選択式または自由形式の回答をランタイム固有のレスポンス形式へ正規化する必要があります。このヘルパーにより、チャネル/TUI の表示は一貫したまま、各ハーネスは独自のプロトコル解析と保留中リクエストのライフサイクルを維持できます。

Pi のようなコンパクトなツールルーティングを必要とするネイティブハーネスは、 openclaw/plugin-sdk/agent-harness-tool-runtime の createAgentHarnessToolSurfaceRuntime(...) を使用する必要があります。これは、ツール検索/コードモードの制御選択、ローカルモデル向けの軽量デフォルト、ランタイム互換のスキーマフィルタリング、非表示カタログの実行、ディレクトリのハイドレーション、およびカタログのクリーンアップを管理します。ハーネスは引き続き、SDK 固有のツール変換とネイティブ実行コールバックを所有します。

ネイティブ Codex ハーネスモード

バンドルされた codex ハーネスは、埋め込み OpenClaw エージェントターン用のネイティブ Codex モードです。まずバンドルされた codex Plugin を有効にし、設定で制限付き許可リストを使用している場合は、plugins.allow に codex を含めます。ネイティブ app-server 設定では openai/gpt-* を使用する必要があります。OpenAI エージェントターンで Codex ハーネスが選択されるのは、有効なルートで Codex 互換性が宣言されている場合のみです。従来の Codex モデル参照は openclaw doctor --fix で修復する必要があります。従来の codex/* モデル参照は、ネイティブハーネスの互換性エイリアスとして残ります。

このモードの実行時、Codex はネイティブスレッド ID、再開動作、Compaction、および app-server の実行を所有します。OpenClaw は引き続き、チャットチャネル、表示可能なトランスクリプトミラー、ツールポリシー、承認、メディア配信、およびセッション選択を所有します。Codex app-server パスのみが実行を引き受けられることを証明する必要がある場合は、プロバイダー/モデル agentRuntime.id: "codex" を使用します。明示的な Plugin ランタイムはフェイルクローズします。Codex app-server の選択失敗およびランタイム障害は、別のランタイム経由では再試行されません。

ランタイムの厳格性

デフォルトでは、OpenClaw は auto プロバイダー/モデルランタイムポリシーを使用します。登録済みの Plugin ハーネスは互換性のある有効なルートを引き受けることができ、一致するものがない場合は埋め込みランタイムがターンを処理します。プロバイダー/モデルのプレフィックスだけでは、ハーネスが選択されることはありません。ハーネスが選択されない場合に埋め込みランタイムへルーティングせず失敗させるには、agentRuntime.id: "codex" などの明示的なプロバイダー/モデル Plugin ランタイムを使用します。明示的に選択しても、互換性のないルートに互換性が生じるわけではありません。選択された Plugin ハーネスの失敗は常にハードエラーになります。これは、明示的なプロバイダー/モデル agentRuntime.id: "openclaw" を妨げません。

Codex 専用の埋め込み実行の場合:

json
{  "models": {    "providers": {      "openai": {        "agentRuntime": {          "id": "codex"        }      }    }  },  "agents": {    "defaults": {      "model": "openai/gpt-5.6-sol"    }  }}

1 つの正規モデルに CLI バックエンドを使用する場合は、そのモデルエントリにランタイムを配置します:

json
{  "agents": {    "defaults": {      "model": "anthropic/claude-opus-4-8",      "models": {        "anthropic/claude-opus-4-8": {          "agentRuntime": {            "id": "claude-cli"          }        }      }    }  }}

エージェント単位のオーバーライドでは、同じモデルスコープの形式を使用します:

json
{  "agents": {    "list": [      {        "id": "codex-only",        "model": "openai/gpt-5.6-sol",        "models": {          "openai/gpt-5.6-sol": {            "agentRuntime": { "id": "codex" }          }        }      }    ]  }}

次のような従来のエージェント全体を対象とするランタイム例は無視されます:

json
{  "agents": {    "defaults": {      "agentRuntime": {        "id": "codex"      }    }  }}

明示的な Plugin ランタイムを使用すると、要求されたハーネスが登録されていない場合、解決されたプロバイダー/モデルをサポートしていない場合、またはターンの副作用を生成する前に失敗した場合、セッションは早期に失敗します。これは、Codex 専用デプロイメント、および Codex app-server パスが実際に使用されていることを証明する必要があるライブテストにおける意図的な動作です。

この設定で制御されるのは、埋め込みエージェントハーネスのみです。画像、動画、音楽、TTS、PDF、またはその他のプロバイダー固有のモデルルーティングは無効になりません。

ネイティブセッションとトランスクリプトミラー

ハーネスは、ネイティブセッション ID、スレッド ID、またはデーモン側の再開トークンを保持できます。そのバインディングを OpenClaw セッションと明示的に関連付けたままにし、ユーザーに表示されるアシスタント/ツール出力を OpenClaw トランスクリプトにミラーリングし続けます。

OpenClaw トランスクリプトは、次の互換性レイヤーとして維持されます:

  • チャネルに表示されるセッション履歴
  • トランスクリプトの検索とインデックス作成
  • 後続のターンで組み込み OpenClaw ハーネスへ戻す切り替え
  • 汎用の /new、/reset、およびセッション削除動作

ハーネスがサイドカーバインディングを保存する場合は、所有元の OpenClaw セッションがリセットされたときに OpenClaw がそれを消去できるよう、reset(...) を実装します。

ツールとメディアの結果

コアは OpenClaw ツールリストを構築し、準備済みの試行へ渡します。ハーネスが動的ツール呼び出しを実行する場合は、チャネルメディアを自身で送信するのではなく、ハーネスの結果形式を通じてツール結果を返します。

これにより、テキスト、画像、動画、音楽、TTS、承認、およびメッセージングツールの出力が、OpenClaw が処理する実行と同じ配信パスに保たれます。

ターミナルツール結果

AgentHarnessAttemptParams.observeToolTerminal は、ホストが所有するターミナル結果アキュムレーターです。OpenClaw の動的ツールまたはネイティブツールを実行するハーネスは、各ツールが 1 つの終端結果に達した時点で、試行結果を確定する前にこれを呼び出す必要があります。ツールを実行しないハーネスは呼び出す必要がありません。

実行境界から得られた事実を報告します:

  • プロトコル呼び出し ID が存在する場合は、その ID、正規のツール名、および準備またはフックによる書き換え後に実際にツールへ渡された引数を渡します。
  • 検証、承認、または別のガードによってツール実装の開始前に呼び出しが停止した場合は、executionStarted: false を設定します。ディスパッチが発生した可能性がある時点からは、保守的に true を報告します。
  • outcome: "success" または outcome: "failure" を報告します。表示テキストから失敗を推測するのではなく、ランタイムから取得可能な構造化された失敗フィールドを含めます。
  • nativeMutation は、OpenClaw ツール定義を使用しないネイティブツールにのみ使用します。そこではプロトコルが所有する変更および再実行の事実を指定し、OpenClaw の変更分類器をハーネスへコピーしないでください。

コールバックは、その呼び出しに対する正規の解決結果を返します。その lastToolError を AgentHarnessAttemptResult に引き継ぎ、並行する状態を導出する代わりに、実行、引数、および副作用に関する事実をハーネス投影で使用します。ホストは、未解決の変更操作失敗を無関係なツールが成功した後も保持し、対応するアクションが成功した後にのみ消去します。

このコールバックは、従来の実験的ハーネスとのソース互換性のため、引き続きオプションです。ただし、ツールを実行するハーネスで無視してよいという意味ではありません。終端レポートがなければ、OpenClaw は、静かな Heartbeat の完了を含む後続のツール呼び出しにわたって、変更ツールの失敗という事実を維持できません。

現在の制限事項

  • 公開インポートパスは汎用ですが、一部の試行/結果型エイリアスには、互換性のため従来の名前が残っています。
  • サードパーティ製ハーネスのインストールは実験的です。ネイティブセッションランタイムが必要になるまでは、プロバイダー Plugin を優先してください。
  • ターン間でのハーネス切り替えはサポートされています。ネイティブツール、承認、アシスタントテキスト、またはメッセージ送信が開始された後に、ターンの途中でハーネスを切り替えないでください。

関連情報

Was this useful?
On this page

On this page