OpenClawエージェントハーネス開発ガイド：ネイティブ実行環境の構築

開発を進めていると、標準的な LLM API だけでは対応しきれない場面に遭遇することがあります。例えば、独自の実行環境でスレッドを細かく制御したり、特定のイベントをネイティブにストリーミングしたりする必要がある場合、通常の抽象化レイヤーでは限界を感じるかもしれません。

OpenClaw では、こうした高度なユースケースに対応するために Agent Harness という仕組みを用意しています。これは、準備されたエージェントの 1 ターンを実行するための低レベルなエグゼキューターです。

Agent Harness Plugins

Agent Harness は、準備された OpenClaw エージェントの 1 ターンを実行するための低レベルなエグゼキューターです。これは Model Provider でも、Channel でも、Tool Registry でもありません。

このインターフェースは、バンドルされたプラグインや信頼できるネイティブプラグインに対してのみ使用してください。パラメータの型が意図的に現在の組み込みランナーを反映しているため、このコントラクトはまだ実験的な段階にあります。

Harness を使用するタイミング

モデルファミリーが独自のネイティブセッションランタイムを持っており、通常の OpenClaw Provider のトランスポートでは適切な抽象化ができない場合に、Agent Harness を登録してください。

例：

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

新しい LLM API を追加するためだけに Harness を登録しないでください。通常の HTTP や WebSocket のモデル API の場合は、Provider Plugin を作成してください。

Core が引き続き管理するもの

Harness が選択される前に、OpenClaw は以下の事項をすでに解決しています。

Provider と Model
ランタイムの認証状態
Thinking Level とコンテキスト予算
OpenClaw の Transcript/セッションファイル
Workspace、Sandbox、および Tool Policy
Channel の返信コールバックとストリーミングコールバック
モデルのフォールバックおよびライブモデル切り替えポリシー

この分離は意図的なものです。Harness は準備された試行（Attempt）を実行するものであり、Provider を選択したり、Channel の配信を置き換えたり、モデルを勝手に切り替えたりすることはありません。

Harness の登録

Import: openclaw/plugin-sdk/agent-harness

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) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});

選択ポリシー

OpenClaw は、Provider と Model が解決された後に Harness を選択します。

OPENCLAW_AGENT_RUNTIME=<id> が設定されている場合、その ID を持つ登録済み Harness を強制的に使用します。
OPENCLAW_AGENT_RUNTIME=pi の場合、組み込みの PI Harness を強制的に使用します。
OPENCLAW_AGENT_RUNTIME=auto の場合、登録された Harness に対して、解決された Provider と Model をサポートしているか確認します。
一致する登録済み Harness がない場合、PI フォールバックが無効化されていない限り、OpenClaw は PI を使用します。

強制されたプラグイン Harness が失敗した場合は、実行エラーとして表面化します。auto モードでは、選択されたプラグイン Harness がターンの副作用（Side effects）を生成する前に失敗した場合、OpenClaw は PI にフォールバックすることがあります。このフォールバックを厳格なエラーにしたい場合は、OPENCLAW_AGENT_HARNESS_FALLBACK=none または embeddedHarness.fallback: "none" を設定してください。

バンドルされている Codex プラグインは、Harness ID として codex を登録しています。Core はこれを通常のプラグイン Harness ID として扱います。Codex 固有のエイリアスは、共有ランタイムセレクターではなく、プラグインまたはオペレーターの設定に記述してください。

Provider と Harness のペアリング

ほとんどの Harness は、Provider も登録する必要があります。Provider は、モデルの参照、認証ステータス、モデルのメタデータ、および /model による選択を OpenClaw の他の部分から見えるようにします。その後、Harness が supports(...) 内でその Provider を要求します。

バンドルされている Codex プラグインはこのパターンに従っています。

Provider ID: codex
ユーザーのモデル参照: codex/gpt-5.4、codex/gpt-5.2、または Codex アプリサーバーから返されるその他のモデル
Harness ID: codex
認証: Codex Harness がネイティブの Codex ログイン/セッションを管理するため、擬似的な Provider の可用性を使用
アプリサーバーへのリクエスト: OpenClaw は生のモデル ID を Codex に送信し、Harness がネイティブのアプリサーバープロトコルと通信

Codex プラグインは追加的なものです。通常の openai/gpt-* 参照は OpenAI Provider の参照として残り、通常の OpenClaw Provider パスを引き続き使用します。Codex 管理の認証、Codex のモデル検出、ネイティブスレッド、および Codex アプリサーバーでの実行が必要な場合にのみ、codex/gpt-* を選択してください。/model を使用すると、OpenAI Provider の認証情報を必要とせずに、Codex アプリサーバーから返された Codex モデル間を切り替えることができます。

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

OpenClaw には Codex アプリサーバー 0.118.0 以降が必要です。Codex プラグインはアプリサーバーの初期化ハンドシェイクをチェックし、古いサーバーやバージョン未指定のサーバーをブロックします。これにより、OpenClaw はテスト済みのプロトコル表面に対してのみ実行されます。

PI フォールバックの無効化

デフォルトでは、OpenClaw は agents.defaults.embeddedHarness を { runtime: "auto", fallback: "pi" } に設定して組み込みエージェントを実行します。auto モードでは、登録されたプラグイン Harness が Provider と Model のペアを要求できます。一致するものがない場合、または自動選択されたプラグイン Harness が出力を生成する前に失敗した場合、OpenClaw は PI にフォールバックします。

特定のプラグイン Harness だけが実行されていることを保証する必要がある場合は、fallback: "none" を設定してください。これにより自動的な PI フォールバックは無効になりますが、明示的な runtime: "pi" や OPENCLAW_AGENT_RUNTIME=pi はブロックされません。

Codex 専用の組み込み実行の設定例：

{
  "agents": {
    "defaults": {
      "model": "codex/gpt-5.4",
      "embeddedHarness": {
        "runtime": "codex",
        "fallback": "none"
      }
    }
  }
}

登録されたプラグイン Harness に一致するモデルを要求させつつ、OpenClaw が PI に自動フォールバックしないようにするには、runtime: "auto" を維持したままフォールバックを無効にします。

{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "none"
      }
    }
  }
}

エージェントごとのオーバーライドも同じ形式を使用します。

{
  "agents": {
    "defaults": {
      "embeddedHarness": {
        "runtime": "auto",
        "fallback": "pi"
      }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "codex/gpt-5.4",
        "embeddedHarness": {
          "runtime": "codex",
          "fallback": "none"
        }
      }
    ]
  }
}

OPENCLAW_AGENT_RUNTIME は、設定されたランタイムを依然として上書きします。環境変数から PI フォールバックを無効にするには、OPENCLAW_AGENT_HARNESS_FALLBACK=none を使用してください。

OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run

フォールバックを無効にすると、要求された Harness が登録されていない場合、解決された Provider と Model をサポートしていない場合、またはターンの副作用を生成する前に失敗した場合に、セッションは早期に失敗します。これは、Codex 専用のデプロイメントや、Codex アプリサーバーのパスが実際に使用されていることを証明する必要があるライブテストにおいて意図された挙動です。

この設定は組み込みの Agent Harness のみを制御します。画像、動画、音楽、TTS、PDF、またはその他の Provider 固有のモデルルーティングを無効にするものではありません。

ネイティブセッションと Transcript のミラーリング

Harness は、ネイティブのセッション ID、スレッド ID、またはデーモン側の Resume Token を保持する場合があります。そのバインディングを OpenClaw セッションと明示的に関連付け、ユーザーに見える Assistant や Tool の出力を OpenClaw の Transcript にミラーリングし続けてください。

OpenClaw の Transcript は、以下の機能のための互換レイヤーとして機能します。

Channel から見えるセッション履歴
Transcript の検索とインデックス作成
後続のターンで組み込みの PI Harness に戻る機能
汎用的な /new、/reset、およびセッション削除の動作

Harness がサイドカーバインディングを保存する場合は、所有する OpenClaw セッションがリセットされたときに OpenClaw がそれをクリアできるように reset(...) を実装してください。

Tool とメディアの結果

Core は OpenClaw のツールリストを構築し、準備された試行（Attempt）に渡します。Harness が動的なツール呼び出しを実行した場合は、Channel メディアを自分で送信するのではなく、Harness の結果形式を通じてツールの結果を返してください。

これにより、テキスト、画像、動画、音楽、TTS、承認、およびメッセージングツールの出力が、PI を使用した実行と同じ配信パスに維持されます。

現在の制限事項

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

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。