エージェントハーネス Plugin

​

ハーネスを使用する場合

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

​

コアが引き続き管理するもの

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

​

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

​

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

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

​

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

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

​

ハーネスを登録する

import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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);
  },
});

​

委任された実行

​

選択ポリシー

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

​

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

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

​

ツール結果ミドルウェア

​

ターミナル結果の分類

​

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

​

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

​

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

​

ランタイムの厳格性

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

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-5",
      "models": {
        "anthropic/claude-opus-5": {
          "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"
      }
    }
  }
}

​

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

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

​

ツールとメディアの結果

​

ターミナルツールの結果

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

​

確定済みツールの最終処理

• 制限された正確なネイティブトランスクリプト、または確定済みツール結果の境界まで固定された完全なアプリケーショントランスクリプトのいずれかを使用すること。
• ツール、権限付与またはユーザー入力機能、ネイティブ実行フック、エージェント、Skills、メモリ、スケジューリング、拡張機能、リモート制御を一切公開しないこと。
• ホストが提供する最終処理プロンプトのみを送信すること。
• 選択したトランスクリプト/分離戦略でこれらの制限を適用できない場合は、フェイルクローズすること。

​

現在の制限事項

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

​

関連項目

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