English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Fundamentals

エージェントランタイム

エージェントランタイムは、準備済みのモデルループを1つ所有するコンポーネントです。プロンプトを受け取り、モデル出力を駆動し、ネイティブツール呼び出しを処理して、完了したターンを OpenClaw に返します。

ランタイムとプロバイダーはどちらもモデル設定の近くに現れるため混同しやすいですが、異なるレイヤーです。

レイヤー 例 意味
プロバイダー openai, anthropic, openai-codex OpenClaw が認証し、モデルを検出し、モデル参照に名前を付ける方法。
モデル gpt-5.5, claude-opus-4-6 エージェントターンで選択されるモデル。
エージェントランタイム pi, codex, claude-cli 準備済みターンを実行する低レベルのループまたはバックエンド。
チャネル Telegram, Discord, Slack, WhatsApp メッセージが OpenClaw に出入りする場所。

コード内では ハーネス という語も見かけます。ハーネスは、エージェントランタイムを提供する実装です。たとえば、同梱の Codex ハーネスは codex ランタイムを実装します。公開設定では agentRuntime.id を使用します。openclaw doctor --fix は古いランタイムポリシーキーをその形に書き換えます。

ランタイムファミリーは2つあります。

  • 埋め込みハーネスは、OpenClaw の準備済みエージェントループ内で実行されます。現在は組み込みの pi ランタイムと、codex などの登録済み Plugin ハーネスです。
  • CLI バックエンドは、モデル参照を正規のまま保ちながらローカル CLI プロセスを実行します。たとえば、agentRuntime.id: "claude-cli" と併用した anthropic/claude-opus-4-7 は、「Anthropic モデルを選択し、Claude CLI 経由で実行する」という意味です。claude-cli は埋め込みハーネス ID ではなく、AgentHarness 選択に渡してはいけません。

Codex サーフェス

混乱の多くは、Codex という名前を共有する複数の異なるサーフェスから生じます。

サーフェス OpenClaw 名/設定 役割
ネイティブ Codex app-server ランタイム openai/* モデル参照 Codex app-server 経由で OpenAI 埋め込みエージェントターンを実行します。これは通常の ChatGPT/Codex サブスクリプション設定です。
Codex OAuth 認証プロファイル openai-codex 認証プロバイダー Codex app-server ハーネスが消費する ChatGPT/Codex サブスクリプション認証を保存します。
Codex ACP アダプター runtime: "acp", agentId: "codex" 外部 ACP/acpx コントロールプレーン経由で Codex を実行します。ACP/acpx が明示的に要求された場合にのみ使用します。
ネイティブ Codex チャット制御コマンドセット /codex ... チャットから Codex app-server スレッドをバインド、再開、誘導、停止、検査します。
非エージェントサーフェス向け OpenAI Platform API ルート openai/* と API キー認証 画像、埋め込み、音声、リアルタイムなどの直接 OpenAI API に使用されます。

これらのサーフェスは意図的に独立しています。codex Plugin を有効にすると、ネイティブ app-server 機能が利用可能になります。openclaw doctor --fix は、レガシーの openai-codex/* ルート修復と古いセッションピンのクリーンアップを担当します。エージェントモデルで openai/* を選択すると、非エージェント OpenAI API サーフェスを使用している場合を除き、現在は「これを Codex 経由で実行する」という意味になります。

一般的な ChatGPT/Codex サブスクリプション設定では、認証に Codex OAuth を使用しますが、モデル参照は openai/* のままにし、codex ランタイムを選択します。

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}

これは、OpenClaw が OpenAI モデル参照を選択し、その後 Codex app-server ランタイムに埋め込みエージェントターンの実行を依頼することを意味します。「API 課金を使用する」という意味ではなく、チャネル、モデルプロバイダーカタログ、または OpenClaw セッションストアが Codex になるという意味でもありません。

同梱の codex Plugin が有効な場合、自然言語の Codex 制御には ACP ではなくネイティブ /codex コマンドサーフェス（/codex bind, /codex threads, /codex resume, /codex steer, /codex stop）を使用してください。Codex に ACP を使用するのは、ユーザーが ACP/acpx を明示的に要求した場合、または ACP アダプターパスをテストしている場合のみです。Claude Code、Gemini CLI、OpenCode、Cursor、および同様の外部ハーネスは引き続き ACP を使用します。

これはエージェント向けの判断ツリーです。

  1. ユーザーが Codex のバインド/制御/スレッド/再開/誘導/停止 を要求する場合、同梱の codex Plugin が有効ならネイティブ /codex コマンドサーフェスを使用します。
  2. ユーザーが 埋め込みランタイムとしての Codex を要求する場合、または通常のサブスクリプションベースの Codex エージェント体験を望む場合は、openai/<model> を使用します。
  3. ユーザーが OpenAI モデルに PI を明示的に選択する場合、モデル参照は openai/<model> のままにし、agentRuntime.id: "pi" を設定します。選択された openai-codex 認証プロファイルは、PI のレガシー Codex 認証トランスポートを通じて内部的にルーティングされます。
  4. レガシー設定にまだ openai-codex/* モデル参照 が含まれている場合は、openclaw doctor --fix で openai/<model> に修復します。
  5. ユーザーが ACP、acpx、または Codex ACP アダプター を明示的に指定した場合は、runtime: "acp" と agentId: "codex" で ACP を使用します。
  6. 要求が Claude Code、Gemini CLI、OpenCode、Cursor、Droid、または別の外部ハーネス 向けの場合は、ネイティブサブエージェントランタイムではなく ACP/acpx を使用します。
意図していること... 使用するもの...
Codex app-server チャット/スレッド制御 同梱の codex Plugin の /codex ...
Codex app-server 埋め込みエージェントランタイム openai/* エージェントモデル参照
OpenAI Codex OAuth openai-codex 認証プロファイル
Claude Code またはその他の外部ハーネス ACP/acpx

OpenAI ファミリープレフィックスの分割については、OpenAI と モデルプロバイダー を参照してください。Codex ランタイムサポート契約については、Codex ハーネス を参照してください。

ランタイムの所有権

ランタイムごとに、ループのどの程度を所有するかが異なります。

サーフェス OpenClaw PI 埋め込み Codex app-server
モデルループの所有者 PI 埋め込みランナー経由の OpenClaw Codex app-server
正規スレッド状態 OpenClaw トランスクリプト Codex スレッドと OpenClaw トランスクリプトミラー
OpenClaw 動的ツール ネイティブ OpenClaw ツールループ Codex アダプター経由でブリッジ
ネイティブシェルおよびファイルツール PI/OpenClaw パス Codex ネイティブツール。対応している場合はネイティブフック経由でブリッジ
コンテキストエンジン ネイティブ OpenClaw コンテキスト組み立て OpenClaw がコンテキストを Codex ターンに組み立てる
Compaction OpenClaw または選択されたコンテキストエンジン Codex ネイティブ Compaction。OpenClaw 通知とミラー保守を伴う
チャネル配信 OpenClaw OpenClaw

この所有権の分割が主な設計ルールです。

  • OpenClaw がサーフェスを所有する場合、OpenClaw は通常の Plugin フック動作を提供できます。
  • ネイティブランタイムがサーフェスを所有する場合、OpenClaw にはランタイムイベントまたはネイティブフックが必要です。
  • ネイティブランタイムが正規スレッド状態を所有する場合、OpenClaw は未対応の内部を書き換えるのではなく、ミラーしてコンテキストを投影するべきです。

ランタイム選択

OpenClaw は、プロバイダーとモデルの解決後に埋め込みランタイムを選択します。

  1. セッションに記録されたランタイムが優先されます。設定変更によって既存のトランスクリプトが別のネイティブスレッドシステムへホットスイッチされることはありません。
  2. OPENCLAW_AGENT_RUNTIME=<id> は、新規またはリセットされたセッションに対してそのランタイムを強制します。
  3. agents.defaults.agentRuntime.id または agents.list[].agentRuntime.id には、auto、pi、codex などの登録済み埋め込みハーネス ID、または claude-cli などの対応 CLI バックエンド別名を設定できます。
  4. auto モードでは、登録済み Plugin ランタイムが対応するプロバイダー/モデルの組み合わせを要求できます。
  5. auto モードでどのランタイムもターンを要求しない場合、OpenClaw は互換性ランタイムとして PI を使用します。実行を厳密にする必要がある場合は、明示的なランタイム ID を使用してください。

明示的な Plugin ランタイムはフェイルクローズします。たとえば、agentRuntime.id: "codex" は Codex または明確な選択/ランタイムエラーを意味し、PI に黙って戻されることはありません。

CLI バックエンド別名は、埋め込みハーネス ID とは異なります。推奨される Claude CLI 形式は次のとおりです。

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

claude-cli/claude-opus-4-7 のようなレガシー参照は互換性のため引き続きサポートされますが、新しい設定ではプロバイダー/モデルを正規のまま保ち、実行バックエンドを agentRuntime.id に配置するべきです。

auto モードは、ほとんどのプロバイダーに対して意図的に保守的です。OpenAI エージェントモデルは例外です。未設定のランタイムと auto はどちらも Codex ハーネスに解決されます。明示的な PI ランタイム設定は、openai/* エージェントターン向けのオプトイン互換ルートとして残ります。選択された openai-codex 認証プロファイルと組み合わせた場合、OpenClaw は公開モデル参照を openai/* のまま保ちながら、PI を内部的にレガシー Codex 認証トランスポート経由でルーティングします。明示的な設定のない古い OpenAI PI セッションピンは Codex に修復されます。

openclaw doctor が、codex Plugin が有効なのに設定に openai-codex/* が残っていると警告する場合、それはレガシールート状態として扱ってください。openclaw doctor --fix を実行して、Codex ランタイムを使う openai/* に書き換えます。

互換性契約

ランタイムが PI でない場合、そのランタイムがどの OpenClaw サーフェスをサポートするかを文書化するべきです。ランタイムドキュメントにはこの形を使用してください。

質問 重要な理由
モデルループを誰が所有するか？ 再試行、ツール継続、最終回答の判断がどこで行われるかを決定します。
正規スレッド履歴を誰が所有するか？ OpenClaw が履歴を編集できるか、ミラーするだけかを決定します。
OpenClaw 動的ツールは動作するか？ メッセージング、セッション、cron、OpenClaw 所有ツールはこれに依存します。
動的ツールフックは動作するか？ Plugin は OpenClaw 所有ツールの周囲で before_tool_call、after_tool_call、ミドルウェアを期待します。
ネイティブツールフックは動作するか？ シェル、パッチ、ランタイム所有ツールには、ポリシーと観測のためのネイティブフックサポートが必要です。
コンテキストエンジンのライフサイクルは実行されるか？ メモリおよびコンテキスト Plugin は、組み立て、取り込み、ターン後、Compaction のライフサイクルに依存します。
どの Compaction データが公開されるか？ 一部の Plugin は通知だけを必要としますが、他の Plugin は保持/削除メタデータを必要とします。
意図的に未対応なのは何か？ ネイティブランタイムがより多くの状態を所有する場所で、ユーザーが PI と同等だと想定しないようにする必要があります。

Codex ランタイムのサポート契約は Codex ハーネスに記載されています。

ステータスラベル

ステータス出力には Execution と Runtime の両方のラベルが表示される場合があります。これらは プロバイダー名ではなく、診断情報として読んでください。

  • openai/gpt-5.5 のようなモデル参照は、選択されたプロバイダー/モデルを示します。
  • codex のようなランタイム ID は、どのループがターンを実行しているかを示します。
  • Telegram や Discord のようなチャンネルラベルは、会話がどこで行われているかを示します。

ランタイム設定を変更した後もセッションに PI が表示される場合は、/new で新しいセッションを開始するか、/reset で現在のセッションをクリアしてください。既存のセッションは記録済みのランタイムを保持するため、トランスクリプトが互換性のない 2 つのネイティブセッションシステムで再生されることはありません。

関連