<!-- source: https://deepwiki.com/openclaw/openclaw/3-agent-runtime -->

# Agent Runtime

- extensions/codex/src/app-server/dynamic-tool-build.test.ts
- extensions/codex/src/app-server/dynamic-tool-build.ts
- src/agents/agent-command.live-model-switch.test.ts
- src/agents/agent-command.ts
- src/agents/agent-scope.test.ts
- src/agents/agent-scope.ts
- src/agents/cli-runner.runtime.ts
- src/agents/embedded-agent-runner/compact.hooks.harness.ts
- src/agents/embedded-agent-runner/compact.ts
- src/agents/embedded-agent-runner/run/attempt-session.ts
- src/agents/embedded-agent-runner/run/attempt-trajectory-flush-cleanup.test.ts
- src/agents/embedded-agent-runner/run/attempt-trajectory-flush-cleanup.ts
- src/agents/embedded-agent-runner/run/attempt.spawn-workspace.test-support.ts
- src/agents/embedded-agent-runner/run/attempt.ts
- src/agents/embedded-agent-runner/system-prompt.test.ts
- src/agents/embedded-agent-runner/system-prompt.ts
- src/agents/runtime-plan/tools.test.ts
- src/agents/runtime-plan/tools.ts
- src/agents/sessions/agent-session.ts
- src/agents/sessions/sdk.test.ts
- src/agents/tool-schema-projection.test.ts
- src/agents/tool-schema-projection.ts
- src/agents/tool-schema-quarantine.test.ts
- src/agents/tool-schema-quarantine.ts
- src/agents/tools-effective-inventory-build.ts
- src/agents/tools-effective-mcp-inventory.ts
- src/auto-reply/get-reply-options.types.ts
- src/auto-reply/reply/agent-runner-cli-dispatch.test.ts
- src/auto-reply/reply/agent-runner-cli-dispatch.ts
- src/auto-reply/reply/agent-runner-execution.test.ts
- src/auto-reply/reply/agent-runner-execution.ts
- src/auto-reply/reply/current-turn-images.ts
- src/auto-reply/reply/followup-runner.test.ts
- src/auto-reply/reply/followup-runner.ts
- src/auto-reply/reply/get-reply-directives.ts
- src/auto-reply/reply/get-reply-run.media-only.test.ts
- src/auto-reply/reply/get-reply-run.ts
- src/auto-reply/reply/get-reply.ts
- src/auto-reply/reply/model-selection.test.ts
- src/auto-reply/reply/model-selection.ts
- src/auto-reply/reply/queue/types.ts
- src/channels/plugins/setup-helpers.test.ts
- src/commands/agent.test.ts
- src/cron/isolated-agent/run.cron-model-override-forwarding.test.ts
- src/plugins/contracts/run-context-lifecycle.contract.test.ts
- src/plugins/runtime/runtime-tasks.test.ts
- src/plugins/status.registry-snapshot.test.ts
- src/plugins/web-provider-runtime-shared.test.ts

The Agent Runtime is OpenClaw's execution engine for AI agent interactions. It orchestrates model calls, tool execution, context management, and session state across multiple providers (OpenAI, Anthropic, Google, etc.). This system is powered by Pi Agent Core and OpenClaw-specific extensions for sandboxing, memory, authentication, and failover.

The runtime handles the translation of natural language intents into structured code execution and model interactions, managing the state transitions between user inputs and agent responses.

## Architecture Overview

The Agent Runtime consists of several interconnected systems that bridge high-level agent logic with low-level model providers and local system tools. It utilizes a lane-based execution model to manage concurrency, specifically using `CommandLane` to prioritize different types of tasks [src/auto-reply/reply/agent-runner-execution.ts67](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L67-L67)

### System Architecture Diagram

The following diagram illustrates how the high-level runtime concepts map to the internal code structure.

```

```

Sources: [src/auto-reply/reply/get-reply-run.ts46](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/get-reply-run.ts#L46-L46) [src/auto-reply/reply/agent-runner-execution.ts40-44](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L40-L44) [src/agents/agent-command.ts103](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-command.ts#L103-L103) [src/auto-reply/reply/followup-runner.ts43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/followup-runner.ts#L43-L43)

## Execution Pipeline

The execution pipeline manages the high-level lifecycle of an agent interaction, including model selection, authentication profile rotation, and error handling. It utilizes `runWithModelFallback` to orchestrate retries across different model providers if the primary fails [src/auto-reply/reply/agent-runner-execution.ts44](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L44-L44)

- Retry & Failover: The system uses MAX_LIVE_SWITCH_RETRIES to prevent infinite ping-pong when session selections conflict with fallback choices src/auto-reply/reply/agent-runner-execution.ts 122
- Authentication Resolution: Credentials are resolved via resolveRunAuthProfile , which handles profile mapping for the specific provider src/auto-reply/reply/agent-runner-execution.ts 88
- Error Classification: Results are analyzed by classifyProviderRequestError to identify transient vs. terminal failures src/auto-reply/reply/agent-runner-execution.ts 107-109

For details, see [Execution Pipeline](/openclaw/openclaw/3.1-execution-pipeline).

Sources: [src/auto-reply/reply/agent-runner-execution.ts44-122](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L44-L122) [src/auto-reply/reply/agent-runner-execution.ts88-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L88-L109)

## System Prompt & Context

OpenClaw constructs dynamic system prompts by merging modular sections based on the session type and environment.

- Modular Construction: The prompt is wrapped in an envelope using buildReplyPromptEnvelope which adds context about the environment and agent capabilities src/auto-reply/reply/get-reply-run.ts 84
- Inbound Metadata: Context about the message origin (e.g., sender info, channel type) is added via buildInboundMetaSystemPrompt src/auto-reply/reply/get-reply-run.ts 78
- Group Context: Specific logic for group chats is handled by buildGroupChatContext and buildGroupIntro src/auto-reply/reply/get-reply-run.ts 72-73
- Skill Injection: Runtime skills are injected into the prompt via resolveSkillsPromptForRun src/agents/embedded-agent-runner/run/attempt.ts 61

For details, see [System Prompt & Context](/openclaw/openclaw/3.2-system-prompt-and-context).

Sources: [src/auto-reply/reply/get-reply-run.ts72-84](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/get-reply-run.ts#L72-L84) [src/agents/embedded-agent-runner/run/attempt.ts61](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run/attempt.ts#L61-L61)

## Model Providers & Authentication

OpenClaw supports a wide array of providers through a normalization layer that handles disparate API schemas.

- Provider Routing: The runtime determines the provider based on the message origin using resolveOriginMessageProvider src/auto-reply/reply/agent-runner-execution.ts 105
- Authentication Modes: Models are matched with credentials via resolveModelAuthMode src/agents/embedded-agent-runner/run/attempt.ts 158
- OAuth Handling: Failures in OAuth token refreshes are classified and can trigger login commands via buildOAuthRefreshFailureLoginCommand src/auto-reply/reply/agent-runner-execution.ts 21-23

For details, see [Model Providers & Authentication](/openclaw/openclaw/3.3-model-providers-and-authentication).

Sources: [src/auto-reply/reply/agent-runner-execution.ts21-105](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L21-L105) [src/agents/embedded-agent-runner/run/attempt.ts158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run/attempt.ts#L158-L158)

## Tools System

The tool system provides agents with capabilities to interact with the local environment and external services.

- Tool Policies: Access is governed by policies resolved via resolveEffectiveToolPolicy src/agents/embedded-agent-runner/run/attempt.ts 102
- Coding Tools: Specialized tools for file manipulation and shell execution are created via createOpenClawCodingTools src/agents/embedded-agent-runner/run/attempt.ts 97
- Messaging Tools: Agents can send messages to other channels using tools detected via isMessagingToolSendAction src/auto-reply/reply/agent-runner-execution.ts 39

For details, see [Tools System](/openclaw/openclaw/3.4-tools-system).

Sources: [src/agents/embedded-agent-runner/run/attempt.ts97-102](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run/attempt.ts#L97-L102) [src/auto-reply/reply/agent-runner-execution.ts39](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L39-L39)

## Commands & Auto-Reply

The runtime features a command registry and auto-reply logic for processing user directives.

- Command Detection: The gateway checks for control commands in user input via hasControlCommand src/auto-reply/reply/get-reply-run.ts 46
- Auto-Reply Runner: The runPreparedReply function serves as the primary entry point for channel-initiated responses src/auto-reply/reply/get-reply-run.ts 46
- Directives: Users can influence agent behavior using inline directives like /think or /verbose , which are parsed via resolveReplyDirectives src/auto-reply/reply/get-reply.ts 34

For details, see [Commands & Auto-Reply](/openclaw/openclaw/3.5-commands-and-auto-reply).

Sources: [src/auto-reply/reply/get-reply-run.ts46](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/get-reply-run.ts#L46-L46) [src/auto-reply/reply/get-reply.ts34](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/get-reply.ts#L34-L34)

## Context Compaction

When a session history becomes too large for the model's context window, the runtime triggers compaction.

- Preflight Checks: runPreflightCompactionIfNeeded ensures the session is within limits before a run starts src/auto-reply/reply/followup-runner.ts 43
- Automatic Guard: Compaction settings are applied from configuration via applyAgentCompactionSettingsFromConfig src/agents/embedded-agent-runner/run/attempt.ts 87
- Session Accounting: The runtime tracks compaction events per session using incrementRunCompactionCount src/auto-reply/reply/followup-runner.ts 63

For details, see [Context Compaction](/openclaw/openclaw/3.6-context-compaction).

Sources: [src/auto-reply/reply/followup-runner.ts43-63](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/followup-runner.ts#L43-L63) [src/agents/embedded-agent-runner/run/attempt.ts87](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run/attempt.ts#L87-L87)

## Automation & ACP

The runtime supports complex orchestration through built-in scheduling and the Agent Control Protocol (ACP).

- Sub-Agents: The runtime identifies sub-agent interactions using isSubagentSessionKey src/routing/session-key.js 38
- Followup Runs: Background tasks and follow-ups are managed via the FollowupRun queue src/auto-reply/reply/followup-runner.ts 57-58
- ACP Integration: Spawning new agent instances is controlled via isAcpRuntimeSpawnAvailable src/agents/embedded-agent-runner/run/attempt.ts 6

For details, see [Automation & Cron](/openclaw/openclaw/3.7-automation-and-cron) and [ACP & Sub-Agents](/openclaw/openclaw/3.8-acp-and-sub-agents).

Sources: [src/routing/session-key.js38](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.js#L38-L38) [src/auto-reply/reply/followup-runner.ts57-58](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/followup-runner.ts#L57-L58) [src/agents/embedded-agent-runner/run/attempt.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/embedded-agent-runner/run/attempt.ts#L6-L6)
