OpenClaw: Prompt Construction & Agent Loop — Deep Analysis

Layer Dependency Graph

2.1 System Prompt Component Assembly Tree

The system uses buildOverridablePromptSection() pattern throughout — each major section can be overridden by a plugin provider's ProviderSystemPromptContribution:

4.1 Run Attempt Lifecycle — 6 Phases

The turn loop is the heart of the agent. Each iteration is one LLM API call that may produce multiple tool calls. The loop continues until the model produces a non-tool-use stop reason.

Turn_Loop:
  while (true):
    # Build context for this turn
    messages = activeSession.agent.state.messages  # includes all prior turns

    # Call LLM — single API request
    response = streamFn(model, messages, options)

    # Parse response for stop_reason
    stop_reason = response.stop_reason

    if stop_reason == "tool_use":
        # Model emitted one or more tool_call blocks
        tool_calls = response.content.blocks.filter(type="tool_use")

        # Execute tool calls
        for each tool_call in tool_calls (sequentially):
            tool_result = execute_tool(tool_call.name, tool_call.input)

            # Append tool_use + tool_result to transcript
            messages.append(tool_use_message(tool_call))
            messages.append(tool_result_message(tool_result))

        # Continue loop — next LLM call gets tool results

    elif stop_reason == "end_turn":
        # Model produced final answer text
        final_text = extract_visible_text(response)
        break

    elif stop_reason == "msg_edit":
        # Model edited a prior message
        apply_message_edit(response)
        break

    else:
        # Other stop reasons: max_tokens, stop_sequence, etc.
        break

  return final_text + payloads

The actual implementation in pi-coding-agent calls streamFn once per turn, which internally handles all tool_calls in the response stream. The transcript is mutated after each tool execution, and the next streamFn call picks up from the updated message list.

streamFn (the LLM streaming function) goes through a multi-stage resolution and wrapping pipeline:

resolveEmbeddedAgentStreamFn(params):
  # Priority 1: Provider-owned stream function
  if params.providerStreamFn:
    return providerStreamFn  # wrapped with auth injection

  # Priority 2: OpenAI WebSocket transport
  if shouldUseWebSocketTransport:
    if wsApiKey:
      return createOpenAIWebSocketStreamFn(...)
    return currentStreamFn  # fallback

  # Priority 3: Anthropic Vertex
  if model.provider == "anthropic-vertex":
    return createAnthropicVertexStreamFn(...)

  # Priority 4: Boundary-aware streaming
  if currentStreamFn == undefined || streamSimple:
    boundaryAware = createBoundaryAwareStreamFnForModel(model)
    if boundaryAware: return boundaryAware

  # Default: use session's streamFn
  return currentStreamFn

1. innerStreamFn = activeSession.agent.streamFn

2. yield-abort wrapper
   → catches sessions_yield abort signal
   → returns createYieldAbortedResponse()

3. sanitize-malformed-tool-calls wrapper
   → fixes whitespace around tool names

4. trim-tool-call-names wrapper
   → normalizes tool names against allowlist

5. repair-malformed-tool-call-arguments wrapper
   → provider-specific argument repair (if needed)

6. decode-xai-tool-call-arguments wrapper
   → HTML entity decoding for xAI

7. anthropic-payload-logger wrapper
   → logs full request/response payloads

8. handle-sensitive-stop-reason wrapper
   → recovers from "sensitive" stop reason

9. idle-timeout wrapper (streamWithIdleTimeout)
   → aborts after idleTimeoutMs of no response

10. diagnostic-model-call-events wrapper
    → emits TrustedDiagnosticEvents for model calls

These wrappers are applied inside the turn loop — wrapping streamFn so every outbound LLM API request passes through sanitization:

Model resolution follows a priority chain in model.ts:

resolveEmbeddedAgentModel(params):
  1. EXPLICIT: params.model — passed directly (highest priority)
  2. CONFIG: params.config → model selection config
  3. RUNTIME: environment variable OPENCLAW_MODEL
  4. DEFAULT: provider-specific default (e.g., claude-3-5-sonnet)

  Then resolve API format:
  - "openai" / "openai-compatible" → OpenAI format
  - "anthropic" → Anthropic format
  - "openai-responses" → OpenAI Responses API
  - "anthropic-vertex" → Anthropic Vertex AI
  - "azure-openai" → Azure OpenAI
  - "openai-codex-responses" → Codex Responses API

The PiModelRegistry in model.ts handles provider plugin registration, inline provider config, and auth storage discovery (reading from ~/.config/openclaw/auth.json or environment variables).

The key design decision: tool calls within a single LLM turn are executed sequentially. The model emits multiple tool_use blocks in one response, but they are processed one at a time in order.

Why Sequential?

• Transcript ordering must be preserved for context coherence
• Tool results are inputs to subsequent tool calls (model may chain)
• Parallel execution would scramble the message sequence the model sees

Where Parallelism DOES Exist:

• MCP tool bundling: Multiple MCP servers' tools are materialized into a single tool list at session creation — this is parallel preparation, not parallel execution
• Session compaction: Background thread compacts session history while new prompts are accepted
• Context engine maintenance: runContextEngineMaintenance() runs in background after each turn
• Hook runners: llm_input hooks fire asynchronously (non-blocking, .catch() fire-and-forget)
• WebSocket streaming: createOpenAIWebSocketStreamFn() uses WebSocket for real-time token delivery
• Diagnostic events: emitTrustedDiagnosticEvent() fires asynchronously

Session compaction is the primary source of genuine parallelism in the agent loop. It runs in parallel with the main loop via activeSession.isCompacting:

Compaction Flow:
  1. After each turn, check if compaction is needed:
     - context-window-guard.js evaluates: tokens_used / max_tokens > threshold

  2. If needed, trigger async compaction:
     activeSession.startCompaction()

  3. Compaction is a Pi Agent operation:
     - Reads full session transcript
     - Summarizes older tool results and intermediate messages
     - Produces a condensed transcript that fits in context window

  4. The main loop continues accepting new prompts DURING compaction:
     - If user sends new message while compacting:
       → abortCompaction() is called
       → new run attempt starts immediately
       → compaction is retried after new turn completes

  5. Compaction safety timeout:
     - compaction-timeout.ts: max compaction duration
     - If exceeded: abortCompaction() + log warning

  6. Preemptive compaction:
     - Before each prompt, check if context is near full
     - If route === "truncate_tool_results_only":
       → truncateOversizedToolResultsInSessionManager()
       → recover without full compaction

Harness selection is a single synchronous decision at run start. It determines which agent backend runs the session:

selectAgentHarness(params):
  # Step 1: Check for pinned harness (session-specific override)
  pinnedPolicy = resolvePinnedAgentHarnessPolicy(agentHarnessId)
  if pinnedPolicy: return resolveToHarness(pinnedPolicy)

  # Step 2: Resolve runtime policy from config/env
  policy = resolveAgentHarnessPolicy(params)
  #   Policy.runtime: "pi" | "auto" | "plugin-id"

  # Step 3a: If runtime == "pi" → use built-in PI harness
  if runtime == "pi":
    return piHarness  # @mariozechner/pi-coding-agent

  # Step 3b: If runtime is a plugin ID → use that plugin harness
  if runtime is registered plugin harness:
    return pluginHarness
  else:
    if policy.fallback == "none":
      throw Error("harness not registered + no fallback")
    log.warn("falling back to PI")
    return piHarness

  # Step 3c: If runtime == "auto" → auto-select based on provider support
  candidates = pluginHarnesses.map(h => ({
    harness,
    support: h.supports({ provider, modelId, runtime })
  }))
  supported = candidates.filter(supported).sorted(byPriority()
  if supported[0]:
    return supported[0].harness  # highest priority
  else:
    if fallback == "none": throw
    return piHarness  # PI is always available as fallback

# FAILOVER: pi-embedded-runner/compact.ts
maybeCompactAgentHarnessSession(params):
  harness = selectAgentHarness(params)
  if harness.compact:
    return harness.compact(params)  # calls PI or plugin compaction
  if harness.id != "pi":
    return { ok: false, reason: "no compact support" }
  return undefined  # PI handles compaction internally

Generated by Hermes · ClawdyHuang Research · Sovereign AI Analysis Framework

Source: github.com/openclaw/openclaw · Analysis Date: April 2026

Key files analyzed: system-prompt.ts (1,048L) · context.ts (21KB) · compact.ts (1,287L) · model.ts (1,121L) · run/attempt.ts (3,290L) · stream-resolution.ts (132L)