エージェントハーネス Plugin

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

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

ハーネスを使用する場合

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

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

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

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

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

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

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

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

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

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

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

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

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

準備済みの試行には params.runtimePlan も含まれます。これは、OpenClaw とネイティブハーネス間で共有され続けなければならないランタイム決定用の、OpenClaw 所有のポリシーバンドルです。

• プロバイダー対応のツールスキーマポリシー用の 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つのハーネスがそのすべてをサポートする必要があります。暗黙的な選択では、完全なセットを所有できるプラグインがない場合、OpenClaw が使用されます。明示的または永続化されたプラグイン選択は、フェイルクローズします。

ハーネスを登録する

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

  const myHarness: AgentHarness = {  id: "my-harness",  label: "独自のネイティブエージェントハーネス",   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: "有効なルートはハーネスと互換性がありません" };  },   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: "独自のネイティブエージェント",  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 ログインとセッションを所有するため、 合成されたプロバイダー可用性を使用
• app-server リクエスト: OpenClaw はモデル id のみを Codex に送信し、 ハーネスがネイティブの app-server プロトコルと通信します

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

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

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

ツール結果ミドルウェア

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

従来の同梱 Plugin は、Codex app-server 専用ミドルウェアに api.registerCodexAppServerExtensionFactory(...)を引き続き使用できますが、 新しい結果変換にはランタイム非依存 API を使用してください。組み込みランナー専用の 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 専用の埋め込み実行の場合:

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

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

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

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

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

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

{  "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 ベースの実行と同じ配信パスに維持されます。

現在の制限事項

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

関連項目

• SDK の概要
• ランタイムヘルパー
• プロバイダー Plugin
• Codex ハーネス
• モデルプロバイダー