エージェントランタイム

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

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

ハーネスは、エージェントランタイムを提供する実装を指すコード用語です。 たとえば、同梱の Codex ハーネスは codex ランタイムを実装します。 公開設定では、プロバイダーまたはモデルのエントリに agentRuntime.id を使用します。エージェント全体の ランタイムキーはレガシーであり、無視されます。openclaw doctor --fix は古い エージェント全体のランタイム固定を削除し、必要に応じてレガシーランタイムのモデル参照を、 正規のプロバイダー／モデル参照とモデルスコープのランタイムポリシーに書き換えます。

ランタイムには2つの系統があります。

• 組み込みハーネスは OpenClaw の準備済みエージェントループ内で実行されます。 組み込みの openclaw ランタイムに加え、codex や copilot など、登録済みの Plugin ハーネスが含まれます。
• CLI バックエンドは、モデル参照を正規のまま維持しつつ、ローカル CLI プロセスを 実行します。たとえば、モデルスコープの agentRuntime.id: "claude-cli" を伴う anthropic/claude-opus-5 は、「Anthropic モデルを選択し、Claude CLI 経由で実行する」ことを意味します。claude-cli は組み込みハーネス ID ではないため、 AgentHarness の選択に渡してはなりません。

copilot ハーネスは、GitHub Copilot CLI 用の独立したオプトインの外部 Plugin ハーネスです。 PI、Codex、GitHub Copilot のエージェントランタイムのうちどれを選ぶかについては、 GitHub Copilot エージェントランタイムを参照してください。

Codex のサーフェス

複数のサーフェスが Codex という名前を共有しています。

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

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

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

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

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

判断ツリー：

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

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

ランタイムの所有範囲

ランタイムごとに、ループを所有する範囲が異なります。

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

ランタイムの選択

OpenClaw は、プロバイダーとモデルを解決した後、次の順序で 組み込みランタイムを解決します。

1. モデルスコープのランタイムポリシーが優先されます。これは、設定済みプロバイダーの モデルエントリ、または agents.defaults.models["provider/model"].agentRuntime ／ agents.entries.*.models["provider/model"].agentRuntime にあります。agents.defaults.models["vllm/*"].agentRuntime などのプロバイダー ワイルドカードは、完全一致のモデルポリシーの後に適用されるため、動的に検出されたプロバイダーモデルは、 モデルごとの完全一致の例外を上書きせずに、1つのランタイムを共有できます。
2. プロバイダースコープのランタイムポリシー：models.providers.<provider>.agentRuntime。
3. auto モード：登録済みの Plugin ランタイムは、対応するプロバイダー／モデルの組み合わせを引き受けることができます。
4. auto モードでどのランタイムもターンを引き受けない場合、OpenClaw は互換ランタイムとして openclaw にフォールバックします。実行を厳密にする必要がある場合は、 明示的なランタイム ID を使用してください。

セッション全体およびエージェント全体のランタイム固定は無視されます：OPENCLAW_AGENT_RUNTIME、 セッションの agentHarnessId/agentRuntimeOverride 状態、agents.defaults.agentRuntime、 および agents.entries.*.agentRuntime。openclaw doctor --fix を実行して、古い エージェント全体のランタイム設定を削除し、意図を維持できる場合は レガシーランタイムのモデル参照を変換してください。

プロバイダー／モデルに明示された Plugin ランタイムはフェイルクローズします。プロバイダーまたはモデル上の agentRuntime.id: "codex" は Codex、または明確な選択／ランタイムエラーを意味し、OpenClaw に暗黙的に ルーティングし直されることはありません。一致しないターンを OpenClaw にルーティングできるのは auto のみです。

CLI バックエンドのエイリアスは、組み込みハーネス ID とは異なります。推奨される Claude CLI の形式：

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

claude-cli/claude-opus-4-7 などのレガシー参照は互換性のため引き続き サポートされますが、新しい設定ではプロバイダー／モデルを正規のまま維持し、 実行バックエンドをプロバイダー／モデルのランタイムポリシーに配置する必要があります。

レガシーの codex-cli/* 参照は異なります。doctor はそれらを openai/* に移行し、 Codex CLI バックエンドを維持する代わりに、Codex app-server ハーネスを通じて 実行されるようにします。

auto モードは、ほとんどのプロバイダーに対して意図的に保守的です。OpenAI エージェント モデルは例外です。ランタイム未設定と auto は、どちらも Codex ハーネスに解決されます。OpenClaw ランタイムの明示的な設定は、openai/* エージェントターン向けの オプトイン互換ルートとして残ります。選択された openai OAuth プロファイルと組み合わせると、OpenClaw は公開モデル参照を openai/* のまま維持しつつ、 そのパスを Codex 認証トランスポートを通じて内部的にルーティングします。古い OpenAI ランタイムのセッション固定はランタイム選択時に無視され、 openclaw doctor --fix でクリーンアップできます。

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

GitHub Copilot エージェントランタイム

外部の @openclaw/copilot Plugin は、GitHub Copilot CLI（@github/copilot-sdk）を基盤とする、オプトインの copilot ランタイムを登録します。これは正規のサブスクリプション github-copilot プロバイダーを使用し、auto によって選択されることは決してありません。agentRuntime.id を使用して、モデルごとまたはプロバイダーごとにオプトインします。

{  agents: {    defaults: {      model: "github-copilot/gpt-5.5",      models: {        "github-copilot/gpt-5.5": {          agentRuntime: { id: "copilot" },        },      },    },  },}

このハーネスは、openclaw doctor が自動的に読み込む extensions/copilot/doctor-contract-api.ts で、プロバイダー、ランタイム、CLI セッションキー、認証プロファイルのプレフィックスを宣言します。設定、認証、トランスクリプトのミラーリング、Compaction、宣言的な doctor コントラクト、および PI、Codex、Copilot の SDK に関するより広範な選択については、GitHub Copilot エージェントランタイムを参照してください。

互換性コントラクト

ランタイムが OpenClaw ではない場合、そのドキュメントには、サポートする OpenClaw のサーフェスを明記する必要があります。

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

ステータスラベル

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

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

実行時に予期しないランタイムが表示された場合は、まず選択されたプロバイダー／モデルのランタイムポリシーを確認してください。レガシーセッションのランタイム固定は、ルーティングを決定しなくなりました。

関連項目

• Codex ハーネス
• Codex ハーネスランタイム
• GitHub Copilot エージェントランタイム
• OpenAI
• エージェントハーネス Plugin
• エージェントループ
• モデル
• ステータス