<!-- source: https://deepwiki.com/openclaw/openclaw/3.1-execution-pipeline -->

# Execution Pipeline

- docs/gateway/config-tools.md
- docs/plugins/codex-computer-use.md
- docs/tools/acp-agents.md
- extensions/codex/src/app-server/dynamic-tool-build.test.ts
- extensions/codex/src/app-server/dynamic-tool-build.ts
- packages/model-catalog-core/src/provider-model-id-normalization.test.ts
- packages/model-catalog-core/src/provider-model-id-normalization.ts
- qa/scenarios/channels/message-tool-stranded-final-reply.md
- src/agents/acp-spawn.test.ts
- src/agents/acp-spawn.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/failover-error.test.ts
- src/agents/failover-error.ts
- src/agents/fallback-skip-cache.test.ts
- src/agents/fallback-skip-cache.ts
- src/agents/model-fallback.test.ts
- src/agents/model-fallback.ts
- src/agents/model-selection-normalize.ts
- src/agents/model-selection-resolve.ts
- src/agents/model-selection-shared.ts
- src/agents/model-selection.test.ts
- src/agents/model-selection.ts
- src/agents/model-thinking-default.ts
- src/agents/model-visibility-policy.ts
- src/agents/openclaw-tools.subagents.sessions-spawn.model.test.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/agent-runner-utils.secret-resolution.test.ts
- src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
- src/auto-reply/reply/agent-runner.ts
- src/auto-reply/reply/bash-command.stop.test.ts
- src/auto-reply/reply/commands-acp.test.ts
- src/auto-reply/reply/commands-acp/lifecycle.ts
- src/auto-reply/reply/commands-acp/runtime-options.ts
- src/auto-reply/reply/commands-core.test.ts
- src/auto-reply/reply/commands-subagents-focus.test.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/pending-tool-task-drain.test.ts
- src/auto-reply/reply/private-message-tool-final.test.ts
- src/auto-reply/reply/private-message-tool-final.ts
- src/auto-reply/reply/queue/types.ts
- src/auto-reply/reply/reply-state.test.ts
- src/auto-reply/reply/session-delivery.ts
- src/auto-reply/reply/session-updates.lifecycle.test.ts
- src/auto-reply/reply/session-updates.test.ts
- src/auto-reply/reply/session-updates.ts
- src/auto-reply/reply/session-usage.ts
- src/auto-reply/reply/session.test.ts
- src/auto-reply/reply/session.ts
- src/channels/plugins/setup-helpers.test.ts
- src/commands/agent.test.ts
- src/commands/models/list.configured.test.ts
- src/commands/models/list.configured.ts
- src/cron/isolated-agent/run.cron-model-override-forwarding.test.ts
- src/gateway/drain-active-sessions-for-shutdown.test.ts
- src/gateway/session-reset-service.ts
- src/plugins/contracts/run-context-lifecycle.contract.test.ts
- src/plugins/provider-runtime.test.ts
- src/plugins/runtime/runtime-tasks.test.ts
- src/plugins/status.registry-snapshot.test.ts
- src/plugins/web-provider-runtime-shared.test.ts
- src/skills/runtime/embedded-run-entries.integration.test.ts
- src/skills/runtime/embedded-run-entries.test.ts
- src/skills/runtime/embedded-run-entries.ts
- src/skills/runtime/session-snapshot.test.ts

The agent execution pipeline transforms an inbound message into a model response. It encompasses directive parsing, command detection, model selection with fallback, auth profile resolution, system prompt construction, tool policy enforcement, streaming response delivery, and context compaction.

This page documents the complete execution flow from message receipt through final reply delivery, focusing on the `runEmbeddedPiAgent` lifecycle and the `runAgentTurnWithFallback` orchestration.

## Execution Stages

The pipeline consists of distinct processing stages, each handling specific aspects of the agent turn lifecycle.

Sources: [src/auto-reply/reply/agent-runner-execution.ts1-120](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L1-L120) [src/auto-reply/reply/agent-runner.ts1-118](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner.ts#L1-L118) [src/auto-reply/reply/get-reply-run.ts1-110](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/get-reply-run.ts#L1-L110)

## Pipeline Call Chain

The execution pipeline routes through nested function calls, each adding retry logic, concurrency control, or error handling.

Sources: [src/auto-reply/reply/agent-runner-execution.ts40-71](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L40-L71) [src/auto-reply/reply/agent-runner.ts91](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner.ts#L91-L91) [src/auto-reply/reply/followup-runner.ts29-65](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/followup-runner.ts#L29-L65)

**Message flow from channel inbound to model API and back**

```

```

Sources: [src/auto-reply/reply/get-reply-run.ts131-150](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/get-reply-run.ts#L131-L150) [src/auto-reply/reply/agent-runner-execution.ts40-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L40-L109) [src/auto-reply/reply/agent-runner-memory.ts43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L43-L43)

## Failover and Retries

The pipeline manages model-level failover and authentication profile rotation by classifying errors to decide whether to retry with the same model, rotate to a different API key, or fail over to a fallback model.

### Error Classification

The pipeline uses `classifyProviderRequestError` [src/auto-reply/reply/agent-runner-execution.ts107-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L107-L109) to map raw provider errors to internal recovery strategies:

- Context Overflow : Detected via isContextOverflowError src/auto-reply/reply/agent-runner-execution.ts 31 or isLikelyContextOverflowError src/auto-reply/reply/agent-runner-execution.ts 33 Triggers compaction.
- Billing : Detected via isBillingErrorMessage src/auto-reply/reply/agent-runner-execution.ts 32
- Rate Limit : Detected via isRateLimitErrorMessage src/auto-reply/reply/agent-runner-execution.ts 35 Triggers profile rotation via resolveRunAuthProfile src/auto-reply/reply/agent-runner-execution.ts 88
- Overloaded : Detected via isOverloadedErrorMessage src/auto-reply/reply/agent-runner-execution.ts 34 Triggers model fallback.
- Live Model Switch : LiveSessionModelSwitchError src/auto-reply/reply/agent-runner-execution.ts 43 occurs when a session is pinned to a model that the current runtime cannot fulfill. The pipeline allows up to MAX_LIVE_SWITCH_RETRIES (2) before failing src/auto-reply/reply/agent-runner-execution.ts 122

Sources: [src/auto-reply/reply/agent-runner-execution.ts20-122](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L20-L122) [src/auto-reply/reply/provider-request-error-classifier.ts107-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/provider-request-error-classifier.ts#L107-L109)

## Context Overflow & Compaction

When a session exceeds the model's context window, the pipeline triggers automatic compaction or truncation via `runPreflightCompactionIfNeeded` [src/auto-reply/reply/agent-runner-memory.ts43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L43-L43)

1. Detection : Checked before every run by comparing estimated session tokens against resolveContextTokensForModel src/auto-reply/reply/agent-runner-execution.ts 26
2. Execution : If required, runPreflightCompactionIfNeeded is called to summarize or truncate history before the model attempt src/auto-reply/reply/agent-runner.ts 78
3. Post-Compaction : The runner reads readPostCompactionContext src/auto-reply/reply/agent-runner.ts 96 to ensure the next turn uses the fresh, compacted state.

Sources: [src/auto-reply/reply/agent-runner-memory.ts43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L43-L43) [src/auto-reply/reply/agent-runner-execution.ts26-37](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L26-L37) [src/auto-reply/reply/agent-runner.ts78-96](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner.ts#L78-L96)

## Code Entity Reference

**Core execution components and their file associations**

```

```

Sources: [src/auto-reply/reply/agent-runner-execution.ts1-122](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-execution.ts#L1-L122) [src/auto-reply/reply/agent-runner-memory.ts43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L43-L43) [src/auto-reply/reply/agent-runner-utils.ts101-102](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-utils.ts#L101-L102) [src/auto-reply/reply/agent-runner-cli-dispatch.ts91-93](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-cli-dispatch.ts#L91-L93)
