Agent Runtime Architecture

OpenClaw is responsible for the built-in agent runtime. The runtime source code is located at src/agents/, model and provider transport logic is in src/llm/, and plugin-facing contracts are exposed through openclaw/plugin-sdk/* barrel exports.

Runtime Layout

Path	Owns
`src/agents/embedded-agent-runner/`	Manages the built-in attempt loop (`run.ts`, `run/`), model selection and provider normalization (`model.ts`), per-provider request parameters (`extra-params.`), compaction, transcript wiring, and session wiring.
`src/agents/sessions/`	Handles session persistence (`session-manager.ts`), resource discovery (`package-manager.ts`, `resource-loader.ts`), in-session `extensions` loading, prompt templates, skills, themes, and TUI-backed tool renderers (`tools/`).
`packages/agent-core/`	Provides a reusable agent core (`@openclaw/agent-core`): the agent loop, harness types, messages, compaction helpers, prompt templates, skills, and session storage contracts.
`src/agents/runtime/`	Acts as the OpenClaw facade, connecting `@openclaw/agent-core` to the plugin SDK LLM runtime and re-exporting it alongside local proxy utilities.
`src/agents/agent-tools*.ts`	Contains OpenClaw-owned tool definitions, parameter schemas, tool policy, before/after tool-call adapters, and host/sandbox edit tools.
`src/agents/agent-hooks/`	Supplies built-in runtime hooks: compaction safeguard, compaction instructions, and context pruning.
`src/agents/harness/`	Manages the harness registry, selection policy, and lifecycle for both built-in and plugin-registered harnesses.
`src/llm/`	Operates the model/provider registry, transport helpers, and provider-specific stream implementations (`src/llm/providers/`).

Boundaries

The core communicates with the built-in runtime through OpenClaw modules and SDK barrels, with no external agent framework packages remaining. Plugins rely on documented openclaw/plugin-sdk/* entrypoints and avoid importing src/** internals.

@earendil-works/pi-tui remains a third-party dependency: a terminal component toolkit used by the local TUI and session tool renderers. Making it internal would require a separate vendoring effort.

Manifests

Resource packages declare OpenClaw resources in package.json metadata. Entries are file paths or globs relative to the package root:

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

Resource types not listed in a manifest fall back to discovery of conventional extensions/, skills/, prompts/, and themes/ directories.

Runtime Selection

The built-in runtime identifier is openclaw. The legacy alias pi normalizes to openclaw; codex-app-server normalizes to codex.
Plugin harnesses register additional runtime ids (for example codex).
Runtime policy is a model/provider-scoped agentRuntime.id configuration (a model entry takes precedence over a provider entry). If unset or default, it resolves to auto.
auto picks a registered plugin harness that supports the effective provider route; otherwise, the built-in OpenClaw runtime is used. A provider or model prefix alone never selects a harness.
OpenAI may implicitly select codex only for an exact official HTTPS Platform Responses or ChatGPT Responses route without an authored request override. Completions adapters, custom endpoints, and routes with authored request behavior remain on openclaw; plaintext official HTTP endpoints are rejected. See OpenAI implicit agent runtime.

Model Runtime Generations

Gateway startup, along with config, plugin, or auth publication, builds one prepared model runtime generation per configured agent. Each generation holds the discovered auth template, model registry, and projected model catalog as a single atomic snapshot. Agent runs fork mutable auth and registry stores from that snapshot; browse, status, cron, doctor, TUI, PDF, and image paths read the published catalog instead of repeating filesystem discovery.

Standalone embedded runtimes publish the same snapshot shape at their activation boundary. A failed or stale generation is never served alongside a newer partial generation; the lifecycle owner must first publish a complete replacement.

Runtime Layout

Boundaries

Manifests

Runtime Selection

Model Runtime Generations

Related