メインコンテンツへスキップ
agent runtimeは、1つの準備済みモデルループを担当するコンポーネントです。プロンプトを受け取り、モデル出力を進め、ネイティブツール呼び出しを処理し、完了したターンをOpenClawに返します。 runtimeは、どちらもモデル設定の近くに現れるため、providerと混同しやすい概念です。これらは別のレイヤーです。
レイヤー例意味
Provideropenai, anthropic, openai-codexOpenClawがどのように認証し、モデルを検出し、model refに名前を付けるか。
Modelgpt-5.5, claude-opus-4-6agentターンに選択されたモデル。
Agent runtimepi, codex, ACP-backed runtimes準備済みターンを実行する低レベルループ。
ChannelTelegram, Discord, Slack, WhatsAppメッセージがOpenClawに入出力される場所。
コードやconfigではharnessという語も見かけます。harnessは、agent runtimeを提供する実装です。たとえば、バンドルされたCodex harnessはcodex runtimeを実装します。互換性のためconfigキー名は引き続きembeddedHarnessですが、ユーザー向けドキュメントやstatus出力では、通常はruntimeと表記すべきです。 一般的なCodexセットアップでは、openai providerとcodex runtimeを使用します。 
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
      },
    },
  },
}
これは、OpenClawがOpenAIのmodel refを選択し、その後Codex app-server runtimeに埋め込みagentターンの実行を依頼することを意味します。channel、モデルprovider catalog、またはOpenClawセッションストアがCodexになることを意味するわけではありません。 OpenAI系プレフィックスの分割については、OpenAIとModel providersを参照してください。Codex runtimeのサポート契約については、Codex harnessを参照してください。

​
Runtime ownership

runtimeごとに、ループのどこまでを担当するかは異なります。
SurfaceOpenClaw Pi embeddedCodex app-server
モデルループの所有者PI embedded runnerを通したOpenClawCodex app-server
正式なスレッド状態OpenClaw transcriptCodex thread、およびOpenClaw transcript mirror
OpenClaw dynamic toolsネイティブなOpenClawツールループCodex adapterを介してブリッジ
ネイティブshellおよびfile toolsPi/OpenClaw経路Codexネイティブtools。サポートされる場合はnative hooks経由でブリッジ
コンテキストエンジンネイティブなOpenClawコンテキスト組み立てOpenClawがプロジェクト化したコンテキストをCodexターンに組み立て
CompactionOpenClawまたは選択されたコンテキストエンジンCodexネイティブCompaction。OpenClaw通知とmirror維持付き
Channel配信OpenClawOpenClaw
このownership分割が主要な設計ルールです。
  • OpenClawがsurfaceを所有している場合、OpenClawは通常のplugin hook動作を提供できます。
  • ネイティブruntimeがsurfaceを所有している場合、OpenClawにはruntime eventsまたはnative hooksが必要です。
  • ネイティブruntimeが正式なスレッド状態を所有している場合、OpenClawはmirrorとコンテキスト投影を行うべきであり、未サポートの内部実装を書き換えるべきではありません。

​
Runtime selection

OpenClawは、providerとmodelの解決後に埋め込みruntimeを選択します。
  1. セッションに記録されたruntimeが優先されます。config変更によって、既存transcriptを別のネイティブthread systemへホットスイッチすることはありません。
  2. OPENCLAW_AGENT_RUNTIME=<id>は、新規またはリセットされたセッションに対してそのruntimeを強制します。
  3. agents.defaults.embeddedHarness.runtimeまたはagents.list[].embeddedHarness.runtimeで、auto、pi、またはcodexのような登録済みruntime idを設定できます。
  4. autoモードでは、登録済みplugin runtimeが対応するprovider/modelの組み合わせを引き受けることができます。
  5. autoモードでどのruntimeもターンを引き受けず、fallback: "pi"が設定されている場合（デフォルト）、OpenClawは互換性フォールバックとしてPiを使用します。未一致のautoモード選択を失敗させたい場合は、fallback: "none"を設定してください。
明示的なplugin runtimeは、デフォルトでfail closedです。たとえば、runtime: "codex"は、同じ上書きスコープでfallback: "pi"を設定しない限り、Codexまたは明確な選択エラーを意味します。runtime overrideはより広いfallback設定を継承しないため、agentレベルのruntime: "codex"が、defaultsでfallback: "pi"を使っていたからといって、暗黙にPiへ戻されることはありません。

​
Compatibility contract

runtimeがPiでない場合、そのruntimeは、どのOpenClaw surfaceをサポートするかを文書化すべきです。runtimeドキュメントには次の形式を使用してください。
問い重要である理由
誰がモデルループを所有するかリトライ、ツール継続、最終回答の判断がどこで行われるかを決定します。
誰が正式なスレッド履歴を所有するかOpenClawが履歴を編集できるのか、mirrorしかできないのかを決定します。
OpenClaw dynamic toolsは動作するかメッセージング、セッション、Cron、およびOpenClaw所有toolsはこれに依存します。
dynamic tool hooksは動作するかpluginは、OpenClaw所有toolsの周囲でbefore_tool_call、after_tool_call、middlewareを期待します。
native tool hooksは動作するかshell、patch、runtime所有toolsには、ポリシーと観測のためnative hookサポートが必要です。
コンテキストエンジンのライフサイクルは動作するかメモリとコンテキストpluginは、assemble、ingest、after-turn、Compactionライフサイクルに依存します。
どのCompactionデータが公開されるかpluginによっては通知だけで十分ですが、保持/破棄メタデータが必要なものもあります。
意図的に未サポートなものは何かネイティブruntimeがより多くの状態を所有する場合、ユーザーはPi同等と想定すべきではありません。
Codex runtimeのサポート契約は、Codex harnessに記載されています。

​
Status labels

status出力にはExecutionとRuntimeの両方のラベルが表示されることがあります。これらはprovider名ではなく診断情報として読んでください。
  • openai/gpt-5.5のようなmodel refは、選択されたprovider/modelを示します。
  • codexのようなruntime idは、どのループがそのターンを実行しているかを示します。
  • TelegramやDiscordのようなchannel labelは、会話がどこで行われているかを示します。
runtime configを変更した後もセッションがPiのまま表示される場合は、/newで新しいセッションを開始するか、/resetで現在のセッションをクリアしてください。既存セッションは記録されたruntimeを保持するため、1つのtranscriptが互換性のない2つのネイティブsession systemを通して再生されることはありません。

​
関連