OpenClaw — Prompt Construction & Agent Loop Deep Analysis

01

System Prompt Construction

All 25+ string components that assemble into the final system prompt, with exact file lineage

System Prompt Assembly — Flow Diagram

Mermaid

flowchart TD
    subgraph BOOTSTRAP["Bootstrap Loading"]
        B1["buildBootstrapPromptWarning()
bootstrap-budget.ts"]
        B2["resolveBootstrapContextForRun()
bootstrap-files.ts"]
        B3["buildFullBootstrapPromptLines()
OR buildLimitedBootstrapPromptLines()
bootstrap-prompt.ts"]
        B4["BOOTSTRAP.md content
.pi/prompts/cl.md · is.md"]
        B1 --> B2 --> B3 --> B4
    end

    subgraph IDENTITY["Identity Layer"]
        I1["'You are a personal assistant
 running inside OpenClaw.'
system-prompt.ts:703"]
    end

    subgraph TOOLING["Tooling Section"]
        T1["buildAgentSystemPrompt()
system-prompt.ts:439"]
        T2["coreToolSummaries map
(read, write, edit, exec...)"]
        T3["26 ordered tool names
toolOrder[] array"]
        T4["External tool summaries
from plugins/params.toolSummaries"]
        T5["Tool Call Style section
(provider overrideable)"]
        T6["Execution Bias section
(provider overrideable)"]
        T1 --> T2 & T3 & T4 --> T5 --> T6
    end

    subgraph SAFETY["Safety & Directives"]
        S1["Safety Constitution
(system-prompt.ts:672-678)"]
        S2["CLI Quick Reference
(system-prompt.ts:777-788)"]
        S3["Self-Update Rules
(system-prompt.ts:793-803)"]
    end

    subgraph DYNAMIC["Dynamic Sections"]
        D1["Skills section
buildSkillsSection()
system-prompt.ts:156"]
        D2["Memory section
buildMemorySection()
system-prompt.ts:174"]
        D3["Docs section
buildDocsSection()
system-prompt.ts:395"]
        D4["Messaging section
buildMessagingSection()
system-prompt.ts:335"]
        D5["Voice (TTS) section
buildVoiceSection()
system-prompt.ts:384"]
        D6["Reactions section
buildReactionGuidance()
system-prompt.ts:912"]
    end

    subgraph WORKSPACE["Workspace Context"]
        W1["Context files loaded
(agents.md, soul.md,
 identity.md, user.md...)"]
        W2["CONTEXT_FILE_ORDER map
(agents.md=10, soul.md=20...)"]
        W3["Stable vs Dynamic split
(dynamic: heartbeat.md)"]
        W4["Project Context sections
buildProjectContextSection()"]
    end

    subgraph RUNTIME["Runtime Footer"]
        R1["SYSTEM_PROMPT_CACHE_BOUNDARY
(--- CACHE BOUNDARY ---)"]
        R2["Runtime line
'Runtime: agent=X | os=Y...'"]
        R3["Heartbeat section
buildHeartbeatSection()"]
        R4["Extra System Prompt
(provider/dynamic suffix)"]
    end

    BOOTSTRAP & IDENTITY & TOOLING & SAFETY --> DYNAMIC
    DYNAMIC --> WORKSPACE --> RUNTIME

    style BOOTSTRAP fill:#0a1628,stroke:#00E5FF,stroke-width:1px,color:#00E5FF
    style IDENTITY fill:#0a1628,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style TOOLING fill:#0a1628,stroke:#00E5FF,stroke-width:1px,color:#00E5FF
    style SAFETY fill:#0a1628,stroke:#FF00AA,stroke-width:1px,color:#FF00AA
    style DYNAMIC fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d
    style WORKSPACE fill:#0a1628,stroke:#FFAB40,stroke-width:1px,color:#FFAB40
    style RUNTIME fill:#0a1628,stroke:#89DDFF,stroke-width:1px,color:#89DDFF

Component Lineage Table — 25 String Components

Component / Function	Source File	Lines	Description
buildAgentSystemPrompt()	src/agents/system-prompt.ts	439–1048	Master builder — orchestrates all sections in order
buildFullBootstrapPromptLines()	src/agents/bootstrap-prompt.ts	1–13	Full bootstrap: read BOOTSTRAP.md, complete workflow
buildLimitedBootstrapPromptLines()	src/agents/bootstrap-prompt.ts	15–25	Limited: explain blocker, suggest next step
BOOTSTRAP.md content	.pi/prompts/cl.md	58 lines	Changelog audit skill — audit entries before release
BOOTSTRAP.md content	.pi/prompts/is.md	22 lines	Issue analysis skill — audit GitHub issues
buildBootstrapPromptWarning()	src/agents/bootstrap-budget.ts	—	Prepends "⚠️ Bootstrap budget..." warning if near limit
buildSkillsSection()	src/agents/system-prompt.ts	156–172	Skills instructions: "scan available_skills..."
buildMemorySection()	src/agents/system-prompt.ts	174–187	Memory citations guidance via plugins/memory-state.ts
buildDocsSection()	src/agents/system-prompt.ts	395–425	Docs links: docs.openclaw.ai, GitHub, Discord, ClawhHub
buildMessagingSection()	src/agents/system-prompt.ts	335–382	sessions_spawn, sessions_send, subagents guidance
buildVoiceSection()	src/agents/system-prompt.ts	384–393	TTS hint via buildTtsSystemPromptHint()
buildHeartbeatSection()	src/agents/system-prompt.ts	127–138	"If heartbeat poll: reply HEARTBEAT_OK"
buildExecutionBiasSection()	src/agents/system-prompt.ts	299–313	"Actionable request: act in this turn..."
buildToolCallStyleSection()	src/agents/system-prompt.ts	747–765	Default: don't narrate routine tool calls
Safety Constitution	src/agents/system-prompt.ts	672–678	No independent goals, prioritize safety, no manipulation
CLI Quick Reference	src/agents/system-prompt.ts	777–788	openclaw gateway status/restart, config.schema.lookup
Self-Update Rules	src/agents/system-prompt.ts	793–803	Updates only on explicit user request
Silent Reply Rules	src/agents/system-prompt.ts	955–970	SILENT_REPLY_TOKEN when nothing to say
buildProjectContextSection()	src/agents/system-prompt.ts	95–125	Loads workspace files: agents.md, soul.md, identity.md...
CONTEXT_FILE_ORDER map	src/agents/system-prompt.ts	44–52	File priority: agents.md(10) → soul.md(20) → ... → memory.md(70)
buildWebchatCanvasSection()	src/agents/system-prompt.ts	275–297	[embed...] directives for webchat only
buildOwnerIdentityLine()	src/agents/system-prompt.ts	232–246	"Authorized senders: [hash or raw numbers]"
buildTimeSection()	src/agents/system-prompt.ts	248–253	"## Current Date & Time — Time zone: {tz}"
SYSTEM_PROMPT_CACHE_BOUNDARY	src/agents/system-prompt-cache-boundary.ts	—	"--- SYSTEM PROMPT CACHE BOUNDARY ---" separator
buildRuntimeLine()	src/agents/system-prompt.ts	1006–1048	"Runtime: agent=X \| os=Y \| node=Z \| model=A \| channel=B"
Provider overrides	src/plugins/provider-runtime.js	—	transformProviderSystemPrompt() wraps final output

Context File Loading Priority

Files are sorted by CONTEXT_FILE_ORDER map then alphabetically. heartbeat.md is marked dynamic (below cache boundary).

agents.md → 10 soul.md → 20 identity.md → 30 user.md → 40 tools.md → 50 bootstrap.md → 60 memory.md → 70 heartbeat.md → dynamic

Bootstrap Prompt Files

.pi/prompts/cl.md — Changelog Audit

---
description: Audit changelog entries
---
Audit changelog entries for all commits
since the last release.

## Process
1. Find last release tag
2. List commits since that tag
3. Read each package's [Unreleased] section
4. Check: skip changelog updates,
   doc-only, release housekeeping
5. Cross-package duplication rule:
   → duplicate to coding-agent
6. Add New Features section
7. Report missing entries

.pi/prompts/is.md — Issue Analysis

---
description: Analyze GitHub issues
---
Analyze GitHub issue(s): $ARGUMENTS

1. Read the issue in full
2. For bugs:
   - Ignore root cause (likely wrong)
   - Read all related code files
   - Trace code path
   - Propose a fix
3. For features:
   - Read related files
   - Propose concise implementation
   - List affected files

Do NOT implement unless asked.

02

The Agent Run Attempt

From runEmbeddedAttempt() to the turn loop — all 3,290 lines of the core agent harness

runEmbeddedAttempt() — High-Level Flow

Mermaid

flowchart TD
    START["User Message
arrives at channel"] --> PREP["Phase 1: Setup
(attempt.ts:579–610)"]
    PREP --> RESOLVE["Phase 2: Resolve
Model + Provider
(model.ts:1–1121)"]
    RESOLVE --> SANDBOX["Phase 3: Sandbox
Context
(sandbox.ts)"]
    SANDBOX --> SESSION["Phase 4: Session
Manager Init
(session-manager-init.ts)"]
    SESSION --> SYSTEMP["Phase 5: System Prompt
buildEmbeddedSystemPrompt()
system-prompt.ts"]
    SYSTEMP --> HOOKS["Phase 6: Hook
Before Prompt Build
llm_input hooks"]
    HOOKS --> PROMPT["Phase 7: Prompt
Assembly
(activeSession.prompt())"]
    PROMPT --> TURN["Turn Loop
(pi-agent-core)"]
    TURN --> TOOL{"tool_use
stop?"}
    TOOL -->|Yes| EXEC["Execute tool
sequentially"]
    EXEC --> APPEND["Append
tool_result
to transcript"]
    APPEND --> TURN
    TOOL -->|No| DONE["Return
final answer"]
    DONE --> COMPACT{"Compaction
needed?"}
    COMPACTION["Compaction
in background
(parallel)"]
    COMPACT -->|Yes| COMPACTION
    COMPACT -->|No| RESULT[("Return
EmbeddedRunAttemptResult")]

    style START fill:#0a1628,stroke:#00E5FF,stroke-width:2px,color:#00E5FF
    style TURN fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style EXEC fill:#0a1628,stroke:#FF00AA,stroke-width:1px,color:#FF00AA
    style COMPACTION fill:#1a0a28,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style DONE fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

runEmbeddedAttempt() — Phase-by-Phase Breakdown

Phase	Lines	Key Functions	Purpose
1. Setup	579–610	resolveUserPath(), AbortController, mkdir workspace	Resolve paths, create abort controller, ensure workspace exists
2. Model Resolution	—	resolveModelAsync(), normalizeResolvedModel()	Resolve provider, model ID, API format (openai/anthropic/etc.)
3. Sandbox	—	resolveSandboxContext()	Determine if running in Docker sandbox, mount paths
4. Session Manager	1284–1290	SessionManager.open(), guardSessionManager()	Open/update session file, install tool result guards
5. System Prompt	1200–1201	buildSystemPromptOverride() → buildEmbeddedSystemPrompt()	Assemble all 25+ prompt components listed in Section 01
6. Hook Runner	2258–2267	resolvePromptBuildHookResult()	Fire llm_input hooks (async, fire-and-forget)
7. Tool Setup	1330–1413	splitSdkTools(), toClientToolDefinitions(), createAgentSession()	Build tool allowlist, create session with tools
8. Stream Wrapping	1556–1866	10× wrapStreamFn*() wrappers	Wrap streamFn with transforms (see Section 03)
9. History Prep	1869–1967	sanitizeSessionHistory(), limitHistoryTurns(), filterHeartbeatPairs()	Prune, truncate, sanitize transcript before LLM call
10. Prompt Submit	2649–2702	activeSession.prompt() — THE CORE CALL	Send to LLM; pi-agent-core handles turn loop internally
11. Compaction Wait	2750–2784	waitForCompactionRetryWithAggregateTimeout()	Wait for background compaction (up to 60s aggregate)
12. Result Return	—	EmbeddedRunAttemptResult	Return transcript, usage metrics, compaction count

Key Insight: The Turn Loop is Inside pi-agent-core

activeSession.prompt() (attempt.ts:2690–2696) delegates the turn loop to @mariozechner/pi-agent-core. That library's prompt() method:

Sends the current transcript (messages + system prompt) to the LLM API
Receives a streaming response
When the model emits tool_use blocks → executes tools sequentially
Appends each tool_result back to the transcript
Loops back to step 1 until stop_reason ≠ "tool_use"
Emits streamed text blocks back to OpenClaw via subscription callbacks

03

Stream Wrapping Chain

10 sequential wrappers that transform the raw LLM stream — applied in layers

Stream Wrapper Stack — Applied Bottom-Up

Mermaid

flowchart LR
    subgraph WRAPPERS["Stream Wrappers (applied bottom-up)"]
        W1["⑩ Diagnostic Events
wrapStreamFnWith
DiagnosticModelCallEvents()
attempt.ts:1853"]
        W2["⑨ Idle Timeout
streamWithIdleTimeout()
llm-idle-timeout.ts"]
        W3["⑧ Sensitive Stop
wrapStreamFnHandle
SensitiveStopReason()
attempt.ts:1829"]
        W4["⑦ Payload Logger
createAnthropic
PayloadLogger().wrapStreamFn()
anthropic-payload-log.ts"]
        W5["⑥ XAI HTML Decode
wrapStreamFnDecode
XaiToolCallArguments()
attempt.ts:1816"]
        W6["⑤ Argument Repair
wrapStreamFnRepair
MalformedToolCallArguments()
attempt.ts:1810"]
        W7["④ Trim Tool Names
wrapStreamFnTrim
ToolCallNames()
attempt.ts:1796"]
        W8["③ Sanitize Tool Calls
wrapStreamFnSanitize
MalformedToolCalls()
attempt.ts:1791"]
        W9["② Yield Abort Gate
anonymous closure
(attempt.ts:1778)"]
        W10["① Provider Transport
resolveEmbedded
AgentStreamFn()
stream-resolution.ts:64"]
    end

    MODEL["LLM API
Provider Transport"]
    OUTPUT["Final Stream
to UI/Subscription"]

    WRAPPERS --> OUTPUT
    MODEL --> WRAPPERS

    style W1 fill:#1a0a28,stroke:#c792ea,stroke-width:1px
    style W2 fill:#1a0a28,stroke:#89DDFF,stroke-width:1px
    style W3 fill:#1a0a28,stroke:#FF5252,stroke-width:1px
    style W4 fill:#0a1628,stroke:#FFAB40,stroke-width:1px
    style W5 fill:#0a1628,stroke:#FF00AA,stroke-width:1px
    style W6 fill:#0a1628,stroke:#00E5FF,stroke-width:1px
    style W7 fill:#0a1628,stroke:#c3e88d,stroke-width:1px
    style W8 fill:#0a1628,stroke:#89DDFF,stroke-width:1px
    style W9 fill:#0a1628,stroke:#FFAB40,stroke-width:1px
    style W10 fill:#0a1628,stroke:#00E5FF,stroke-width:2px

Stream Wrapper Detail

#	Wrapper Function	Source	What It Does
1	resolveEmbeddedAgentStreamFn()	stream-resolution.ts:64	Selects provider transport: OpenAI WS, Anthropic Vertex, or pi streamSimple
2	Yield Abort Gate	attempt.ts:1778	Intercepts "sessions_yield" abort signal; returns createYieldAbortedResponse()
3	wrapStreamFnSanitizeMalformedToolCalls()	attempt.ts:1791	Fixes malformed tool call JSON in streaming response
4	wrapStreamFnTrimToolCallNames()	attempt.ts:1796	Trims whitespace from tool names; guards against unknown-tool loop (threshold: 3)
5	wrapStreamFnRepairMalformedToolCallArguments()	attempt.ts:1810	Repairs malformed JSON args in tool call input blocks
6	wrapStreamFnDecodeXaiToolCallArguments()	attempt.ts:1816	Decodes HTML entities (e.g. <) in xAI tool call arguments
7	createAnthropicPayloadLogger().wrapStreamFn()	anthropic-payload-log.ts	Logs full request/response payloads for debugging
8	wrapStreamFnHandleSensitiveStopReason()	attempt.ts:1829	Catches provider-specific "sensitive" stop reasons before they bubble as errors
9	streamWithIdleTimeout()	llm-idle-timeout.ts	Aborts if model is silent for > idleTimeoutMs (configurable per trigger)
10	wrapStreamFnWithDiagnosticModelCallEvents()	attempt.ts:1853	Emits diagnostic events per model API call (runId, sessionId, provider, model, api, transport)
Conditional wrappers (applied additionally when needed):
C1	wrapStreamFnTextTransforms()	plugin-text-transforms.ts	Provider-specific input/output text transforms (lowercasing, etc.)
C2	cacheTrace.wrapStreamFn()	cache-trace.ts	Records prompt cache stages for observability
C3	Google Prompt Cache	google-prompt-cache.ts	Uses Google's cached prompt feature if available

04

Turn Loop & Parallelism

How the loop handles sequential tool execution, concurrent compaction, and async hooks

Turn Loop — Tool Execution & Parallelism

Mermaid

flowchart TD
    SUBGRAPH TURN["Turn Loop (inside pi-agent-core)"]
        A["LLM emits
tool_use block"] --> B{"Sequential
tool execution?"}
        B -->|Yes| C["Execute Tool 1
(result appended)"]
        C --> D{"More
tool_use?"}
        D -->|Yes| E["Execute Tool 2
(result appended)"]
        E --> F[...]
        F --> D
        D -->|No| G["Next LLM call
with full transcript"]
        G --> A
        A -->|stop_reason ≠ tool_use| H[("Loop exits
Final answer")]
    end

    SUBGRAPH PARALLEL["Parallel Background Activities"]
        P1["Compaction
compactWithSafetyTimeout()
compact.ts:819+"]
        P2["LLM Input Hooks
llm_input hooks
(async fire-and-forget)"]
        P3["Payload Logging
anthropic-payload-log
(async)"]
        P4["Context Engine
assembleAttempt
ContextEngine()"]
    end

    C --> PARALLEL
    E --> PARALLEL

    style TURN fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style PARALLEL fill:#1a0a28,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style H fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

✓ Parallel Activities

Compaction — runs in background while LLM is thinking. Uses compactWithSafetyTimeout() with configurable grace period (compaction-timeout.js). If it overruns, the run proceeds with pre-compaction state.
LLM Input Hooks — llm_input hooks fire asynchronously (fire-and-forget) before each LLM call (attempt.ts:2539–2566). No blocking.
Payload Logging — createAnthropicPayloadLogger records payloads without blocking the stream.
Context Engine — assembleAttemptContextEngine() can preprocess messages in parallel (attempt.ts:1923–1958).
Session Compaction Checkpoint — background snapshot saved during session init (compact.ts:839).

✗ Sequential Only

Tool calls within a turn — always sequential, order-dependent. Model emits tool_use blocks one at a time; each result is appended before the next LLM call.
History truncation — synchronous: limitHistoryTurns() must complete before activeSession.prompt() is called.
System prompt override — synchronous: applySystemPromptOverrideToSession() must complete before prompt().
Abort timer scheduling — synchronous: scheduleAbortTimer() sets up timeout before prompt starts.
Stream wrapper application — synchronous chain applied before any LLM I/O.

Compaction Flow

Compaction — Preemptive vs Background

Mermaid

flowchart TD
    PREEMPT["shouldPreemptivelyCompact
BeforePrompt()
(preemptive-compaction.ts)"]
    PREEMPT -->|overflow tokens| TRUNC["Truncate tool results only
truncateOversized
ToolResultsInSessionManager()"]
    PREEMPT -->|compact_then_truncate| BOTH["Compaction +
then truncation"]
    PREEMPT -->|compact_only| COMP["Compaction only"]

    COMP --> BG["Background
Compaction"]
    BOTH --> BG
    BG --> GRACE["Grace Period
(60s aggregate timeout)"]
    GRACE -->|succeeds| DONE["Use compacted
transcript"]
    GRACE -->|timeout| PREV["Proceed with
pre-compaction state"]
    PREV --> WARN["⚠️ Log warning
timedOutDuring
Compaction=true"]

    style BG fill:#1a0a28,stroke:#c792ea,stroke-width:2px,color:#c792ea
    style PREV fill:#1a0a28,stroke:#FF5252,stroke-width:1px,color:#FF5252
    style TRUNC fill:#0a1628,stroke:#c3e88d,stroke-width:1px,color:#c3e88d

Compaction Guard

After compaction, a CACHE_TTL custom entry is appended to the transcript to prevent double-compaction on the next turn. The guard in prepareCompaction() checks the last entry type before triggering again.

05

Harness Selection

How OpenClaw picks between the built-in pi harness and plugin harnesses (Codex, Claude Code, etc.)

Agent Harness Selection — Decision Tree

Mermaid

flowchart TD
    START["selectAgentHarness()
harness/selection.ts:74"] --> POL["resolvePinned
AgentHarnessPolicy()
OR resolveAgent
HarnessPolicy()"]

    POL --> MODE{"Runtime mode?"}
    MODE -->|"pi"| PI["Return
createPiAgentHarness()
reason: forced_pi"]
    MODE -->|"plugin (forced)"| FIND["Find harness
by ID in registry"]
    FIND -->|found| PLUGIN["Return harness
reason: forced_plugin"]
    FIND -->|not found + fallback≠none| FALLBACK["Fallback to
piHarness
reason: forced_
plugin_fallback_
to_pi"]
    FIND -->|not found + fallback=none| ERROR["Throw Error
'PI fallback disabled'"]
    MODE -->|"auto"| CANDIDATES["Evaluate all
plugin harnesses"]

    CANDIDATES --> SUPPORT{"supports()?"}
    SUPPORT -->|yes| SORT["Sort by priority
(compare
HarnessSupport)"]
    SUPPORT -->|no| SKIP["Skip"]
    SORT --> BEST["Best candidate?"]
    BEST -->|yes| SELECTED["Return harness
reason: auto_plugin"]
    BEST -->|no + fallback=none| ERROR
    BEST -->|no + fallback=pi| PI_FALL["Return piHarness
reason: auto_pi_
fallback"]
    SKIP --> SORT

    PI --> RESULT["AgentHarness
selected"]
    PLUGIN --> RESULT
    FALLBACK --> RESULT
    SELECTED --> RESULT
    PI_FALL --> RESULT

    style PI fill:#0a1628,stroke:#00E5FF,stroke-width:2px,color:#00E5FF
    style PLUGIN fill:#0a1628,stroke:#FF00AA,stroke-width:2px,color:#FF00AA
    style SELECTED fill:#0a1628,stroke:#c3e88d,stroke-width:2px,color:#c3e88d
    style ERROR fill:#1a0a28,stroke:#FF5252,stroke-width:2px,color:#FF5252

Harness Policy Resolution

Selection Reason	Condition	Harness
pinned	agentHarnessId pinned via config	pi or plugin (forced)
forced_pi	runtime="pi" in policy	piHarness (embedded)
forced_plugin	runtime="plugin-id" (specific)	Named plugin harness
forced_plugin_fallback_to_pi	plugin not registered + fallback≠none	piHarness
auto_plugin	runtime="auto" + plugin supports provider	Highest-priority supporting plugin
auto_pi_fallback	runtime="auto" + no plugin supports	piHarness (built-in)

pi-agent-core Imports

The core runtime imports two packages from @mariozechner:

@mariozechner/pi-agent-core @mariozechner/pi-coding-agent @mariozechner/pi-ai

These are the core abstractions: createAgentSession(), SessionManager, estimateTokens(), DefaultResourceLoader, and the StreamFn type.

06

Core Types & Tool Payloads

EmbeddedRunAttemptParams, tool call/request/result types, and session manager interfaces

EmbeddedRunAttemptParams — Key Fields

Field	Type	Description
sessionId	string	Unique run session ID
sessionKey	string	Routing key (user/session)
sessionFile	string	Disk path to session JSON file
provider	string	"anthropic" \| "openai" \| "openai-codex"...
modelId	string	"claude-sonnet-4-7-20250514"
model	ProviderRuntimeModel	Resolved model with api, baseUrl, contextWindow
prompt	string	Current user message
thinkLevel	ThinkLevel	"off" \| "fast" \| "medium" \| "high"
reasoningLevel	ReasoningLevel	"off" \| "summary" \| "block"
timeoutMs	number	Run timeout (default: from config)
config	OpenClawConfig	Full runtime config
workspaceDir	string	Agent working directory
authStorage	AuthStorage	API key storage
toolsAllow	string[]	Explicit tool allowlist
abortSignal	AbortSignal	External abort from gateway

Tool Result Payload Structure

// From run/payloads.ts
ToolUse:      { id, name, input: Record<string, unknown> }
ToolResult:   { toolUseId, content: string }
StopReason:   "tool_use" | "end_turn" | "max_tokens" | "stop_sequence" | ...

// Message flow per turn:
UserMessage → activeSession.prompt() →
  LLM → tool_use{id, "read", {path:"/foo.txt"}} →
  → ToolExecutor.execute("read", {path:"/foo.txt"}) →
  → ToolResult{toolUseId: id, content: "file contents..."} →
  → transcript.push(tool_result) →
  → LLM (next iteration)

07

Complete Architecture

End-to-end flow from user message to LLM API call to response

Full System Architecture

Mermaid

flowchart TD
    CH["User Message
(Telegram/Discord/Signal...)"] --> GW["Gateway
app-lifecycle.ts"]
    GW --> HS["Harness Selection
selectAgentHarness()"]
    HS --> RT["Runtime Plan
buildAgentRuntimePlan()"]
    RT --> ATTEMPT["runEmbeddedAttempt()
attempt.ts:579"]

    subgraph ATTEMPT["runEmbeddedAttempt()"]
        direction TB
        A1["Model Resolution
resolveModelAsync()"] 
        A2["Sandbox Setup
resolveSandboxContext()"]
        A3["Session Manager
SessionManager.open()"]
        A4["System Prompt
buildEmbedded
SystemPrompt()"]
        A5["Tool Registration
createAgentSession()"]
        A6["Stream Wrapping
10× wrapStreamFn()"]
        A7["History Prep
sanitize/filter/limit"]
        A8["HOOK: llm_input
(fire-and-forget)"]
        A9["activeSession
.prompt()"]
        A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> A8 --> A9
    end

    A9 --> LOOP["Turn Loop
(pi-agent-core)"]
    LOOP --> LLM["LLM API Call
(provider transport)"]
    LLM --> RESP{"Response?"}
    RESP -->|tool_use| TOOL["Execute Tool
Sequentially"]
    TOOL --> APPEND["Append
tool_result"]
    APPEND --> LOOP
    RESP -->|final text| DONE["Stream to UI
(subscription)"]
    RESP -->|stop_reason| COMP{"Context
Overflow?"}
    COMP -->|yes| COMPACT["Compaction
(background)"]
    COMP -->|no| OUT["Return result"]

    subgraph PROVIDER["Provider Transports"]
        OPENAI["OpenAI / Azure
OpenAI Responses"]
        ANTHROPIC["Anthropic
Claude API"]
        VERTEX["Anthropic
Vertex"]
        CODEX["OpenAI
Codex"]
    end

    LLM -.->|"provider"| PROVIDER

    subgraph COMPACTION["Compaction System"]
        CP["compactWith
SafetyTimeout()"]
        CT["Context Engine
assembleAttempt
ContextEngine()"]
        CR["rotateTranscript
AfterCompaction()"]
    end

    COMPACT -->|"runs in bg"| CP
    CP --> CT --> CR

    style ATTEMPT fill:#0a1628,stroke:#00E5FF,stroke-width:1px
    style LOOP fill:#0a1628,stroke:#FFAB40,stroke-width:2px,color:#FFAB40
    style COMPACT fill:#1a0a28,stroke:#c792ea,stroke-width:1px,color:#c792ea
    style DONE fill:#0a2820,stroke:#c3e88d,stroke-width:2px,color:#c3e88d

Key Files Referenced

File	Role	Lines
src/agents/system-prompt.ts	Master system prompt builder — all 25+ sections	1,048
src/agents/bootstrap-prompt.ts	Bootstrap prompt lines builder (full/limited)	25
src/agents/context.ts	Memory section and context file handling	—
src/agents/pi-embedded-runner/run/attempt.ts	runEmbeddedAttempt — THE core harness	3,290
src/agents/pi-embedded-runner/compact.ts	Background compaction orchestration	1,287
src/agents/pi-embedded-runner/model.ts	Model resolution + context window cache	1,121
src/agents/pi-embedded-runner/stream-resolution.ts	Stream transport selection (WS/HTTP/Vertex)	132
src/agents/harness/selection.ts	Harness selection decision tree	399
src/agents/pi-embedded-runner/run/payloads.ts	Tool call/request/result type definitions	—
src/plugins/provider-runtime.js	Provider plugin hooks + system prompt transforms	—
src/plugins/memory-state.js	Memory citations prompt section builder	—
src/agents/bootstrap-budget.ts	Bootstrap warning prepend logic	—
src/agents/session-write-lock.js	Session write lock for concurrent safety	—
src/agents/session-compaction-checkpoints.js	Compaction checkpoint snapshot system	—
.pi/prompts/cl.md	Bootstrap skill: Changelog Audit	58
.pi/prompts/is.md	Bootstrap skill: Issue Analysis	22