Agent loop

An agentic loop is the full “real” run of an agent: intake → context assembly → model inference → tool execution → streaming replies → persistence. It’s the authoritative path that turns a message into actions and a final reply, while keeping session state consistent.

In OpenClaw, a loop is a single, serialized run per session that emits lifecycle and stream events as the model thinks, calls tools, and streams output. This doc explains how that authentic loop is wired end-to-end.

Entry points

• Gateway RPC:
  text

  Copy

  agent
  and
  text

  Copy

  agent.wait
  .
• CLI:
  text

  Copy

  agent
  command.

How it works (high-level)

1. text

   Copy

   agent
   RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns
   text

   Copy

   { runId, acceptedAt }
   immediately.
2. text

   Copy

   agentCommand
   runs the agent:
   • resolves model + thinking/verbose/trace defaults
   • loads skills snapshot
   • calls
     text

     Copy

     runEmbeddedPiAgent
     (pi-agent-core runtime)
   • emits lifecycle end/error if the embedded loop does not emit one
3. text

   Copy

   runEmbeddedPiAgent
   :
   • serializes runs via per-session + global queues
   • resolves model + auth profile and builds the pi session
   • subscribes to pi events and streams assistant/tool deltas
   • enforces timeout -> aborts run if exceeded
   • for Codex app-server turns, aborts an accepted turn that stops producing app-server progress before a terminal event
   • returns payloads + usage metadata
4. text

   Copy

   subscribeEmbeddedPiSession
   bridges pi-agent-core events to OpenClaw
   text

   Copy

   agent
   stream:
   • tool events =>
     text

     Copy

     stream: "tool"
   • assistant deltas =>
     text

     Copy

     stream: "assistant"
   • lifecycle events =>
     text

     Copy

     stream: "lifecycle"
     (
     text

     Copy

     phase: "start" | "end" | "error"
     )
5. text

   Copy

   agent.wait
   uses
   text

   Copy

   waitForAgentRun
   :
   • waits for lifecycle end/error for
     text

     Copy

     runId
   • returns
     text

     Copy

     { status: ok|error|timeout, startedAt, endedAt, error? }

Queueing + concurrency

• Runs are serialized per session key (session lane) and optionally through a global lane.
• This prevents tool/session races and keeps session history consistent.
• Messaging channels can choose queue modes (collect/steer/followup) that feed this lane system. See Command Queue.
• Transcript writes are also protected by a session write lock on the session file. The lock is process-aware and file-based, so it catches writers that bypass the in-process queue or come from another process.
• Session write locks are non-reentrant by default. If a helper intentionally nests acquisition of the same lock while preserving one logical writer, it must opt in explicitly with
  text

  Copy

  allowReentrant: true
  .

Session + workspace preparation

• Workspace is resolved and created; sandboxed runs may redirect to a sandbox workspace root.
• Skills are loaded (or reused from a snapshot) and injected into env and prompt.
• Bootstrap/context files are resolved and injected into the system prompt report.
• A session write lock is acquired;
  text

  Copy

  SessionManager
  is opened and prepared before streaming. Any later transcript rewrite, compaction, or truncation path must take the same lock before opening or mutating the transcript file.

Prompt assembly + system prompt

• System prompt is built from OpenClaw’s base prompt, skills prompt, bootstrap context, and per-run overrides.
• Model-specific limits and compaction reserve tokens are enforced.
• See System prompt for what the model sees.

Hook points (where you can intercept)

OpenClaw has two hook systems:

• Internal hooks (Gateway hooks): event-driven scripts for commands and lifecycle events.
• Plugin hooks: extension points inside the agent/tool lifecycle and gateway pipeline.

Internal hooks (Gateway hooks)

• text

  Copy

  agent:bootstrap
  : runs while building bootstrap files before the system prompt is finalized. Use this to add/remove bootstrap context files.
• Command hooks:
  text

  Copy

  /new
  ,
  text

  Copy

  /reset
  ,
  text

  Copy

  /stop
  , and other command events (see Hooks doc).

See Hooks for setup and examples.

Plugin hooks (agent + gateway lifecycle)

These run inside the agent loop or gateway pipeline:

• text

  Copy

  before_model_resolve
  : runs pre-session (no
  text

  Copy

  messages
  ) to deterministically override provider/model before model resolution.
• text

  Copy

  before_prompt_build
  : runs after session load (with
  text

  Copy

  messages
  ) to inject
  text

  Copy

  prependContext
  ,
  text

  Copy

  systemPrompt
  ,
  text

  Copy

  prependSystemContext
  , or
  text

  Copy

  appendSystemContext
  before prompt submission. Use
  text

  Copy

  prependContext
  for per-turn dynamic text and system-context fields for stable guidance that should sit in system prompt space.
• text

  Copy

  before_agent_start
  : legacy compatibility hook that may run in either phase; prefer the explicit hooks above.
• text

  Copy

  before_agent_reply
  : runs after inline actions and before the LLM call, letting a plugin claim the turn and return a synthetic reply or silence the turn entirely.
• text

  Copy

  agent_end
  : inspect the final message list and run metadata after completion.
• text

  Copy

  before_compaction
  /
  text

  Copy

  after_compaction
  : observe or annotate compaction cycles.
• text

  Copy

  before_tool_call
  /
  text

  Copy

  after_tool_call
  : intercept tool params/results.
• text

  Copy

  before_install
  : inspect built-in scan findings and optionally block skill or plugin installs.
• text

  Copy

  tool_result_persist
  : synchronously transform tool results before they are written to an OpenClaw-owned session transcript.
• text

  Copy

  message_received
  /
  text

  Copy

  message_sending
  /
  text

  Copy

  message_sent
  : inbound + outbound message hooks.
• text

  Copy

  session_start
  /
  text

  Copy

  session_end
  : session lifecycle boundaries.
• text

  Copy

  gateway_start
  /
  text

  Copy

  gateway_stop
  : gateway lifecycle events.

Hook decision rules for outbound/tool guards:

• text

  Copy

  before_tool_call
  :
  text

  Copy

  { block: true }
  is terminal and stops lower-priority handlers.
• text

  Copy

  before_tool_call
  :
  text

  Copy

  { block: false }
  is a no-op and does not clear a prior block.
• text

  Copy

  before_install
  :
  text

  Copy

  { block: true }
  is terminal and stops lower-priority handlers.
• text

  Copy

  before_install
  :
  text

  Copy

  { block: false }
  is a no-op and does not clear a prior block.
• text

  Copy

  message_sending
  :
  text

  Copy

  { cancel: true }
  is terminal and stops lower-priority handlers.
• text

  Copy

  message_sending
  :
  text

  Copy

  { cancel: false }
  is a no-op and does not clear a prior cancel.

See Plugin hooks for the hook API and registration details.

Harnesses may adapt these hooks differently. The Codex app-server harness keeps OpenClaw plugin hooks as the compatibility contract for documented mirrored surfaces, while Codex native hooks remain a separate lower-level Codex mechanism.

Streaming + partial replies

• Assistant deltas are streamed from pi-agent-core and emitted as
  text

  Copy

  assistant
  events.
• Block streaming can emit partial replies either on
  text

  Copy

  text_end
  or
  text

  Copy

  message_end
  .
• Reasoning streaming can be emitted as a separate stream or as block replies.
• See Streaming for chunking and block reply behavior.

Tool execution + messaging tools

• Tool start/update/end events are emitted on the
  text

  Copy

  tool
  stream.
• Tool results are sanitized for size and image payloads before logging/emitting.
• Messaging tool sends are tracked to suppress duplicate assistant confirmations.

Reply shaping + suppression

• Final payloads are assembled from:
  • assistant text (and optional reasoning)
  • inline tool summaries (when verbose + allowed)
  • assistant error text when the model errors
• The exact silent token
  text

  Copy

  NO_REPLY
  /
  text

  Copy

  no_reply
  is filtered from outgoing payloads.
• Messaging tool duplicates are removed from the final payload list.
• If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted (unless a messaging tool already sent a user-visible reply).

Compaction + retries

• Auto-compaction emits
  text

  Copy

  compaction
  stream events and can trigger a retry.
• On retry, in-memory buffers and tool summaries are reset to avoid duplicate output.
• See Compaction for the compaction pipeline.

Event streams (today)

• text

  Copy

  lifecycle
  : emitted by
  text

  Copy

  subscribeEmbeddedPiSession
  (and as a fallback by
  text

  Copy

  agentCommand
  )
• text

  Copy

  assistant
  : streamed deltas from pi-agent-core
• text

  Copy

  tool
  : streamed tool events from pi-agent-core

Chat channel handling

• Assistant deltas are buffered into chat
  text

  Copy

  delta
  messages.
• A chat
  text

  Copy

  final
  is emitted on lifecycle end/error.

Timeouts

• text

  Copy

  agent.wait
  default: 30s (just the wait).
  text

  Copy

  timeoutMs
  param overrides.
• Agent runtime:
  text

  Copy

  agents.defaults.timeoutSeconds
  default 172800s (48 hours); enforced in
  text

  Copy

  runEmbeddedPiAgent
  abort timer.
• Cron runtime: isolated agent-turn
  text

  Copy

  timeoutSeconds
  is owned by cron. The scheduler starts that timer when execution begins, aborts the underlying run at the configured deadline, then runs bounded cleanup before recording the timeout so a stale child session cannot keep the lane stuck.
• Stuck-session recovery: with diagnostics enabled,
  text

  Copy

  diagnostics.stuckSessionWarnMs
  detects long
  text

  Copy

  processing
  sessions. Active embedded runs, active reply operations, and active session-lane tasks remain warning-only by default; if diagnostics show no active work for the session, the watchdog releases the affected session lane so queued startup work can drain.
• Model idle timeout: OpenClaw aborts a model request when no response chunks arrive before the idle window.
  text

  Copy

  models.providers.<id>.timeoutSeconds
  extends this idle watchdog for slow local/self-hosted providers; otherwise OpenClaw uses
  text

  Copy

  agents.defaults.timeoutSeconds
  when configured, capped at 120s by default. Cron-triggered runs with no explicit model or agent timeout disable the idle watchdog and rely on the cron outer timeout.
• Provider HTTP request timeout:
  text

  Copy

  models.providers.<id>.timeoutSeconds
  applies to that provider's model HTTP fetches, including connect, headers, body, SDK request timeout, total guarded-fetch abort handling, and model stream idle watchdog. Use this for slow local/self-hosted providers such as Ollama before raising the whole agent runtime timeout.

Where things can end early

• Agent timeout (abort)
• AbortSignal (cancel)
• Gateway disconnect or RPC timeout
• text

  Copy

  agent.wait
  timeout (wait-only, does not stop agent)

Related

• Tools — available agent tools
• Hooks — event-driven scripts triggered by agent lifecycle events
• Compaction — how long conversations are summarized
• Exec Approvals — approval gates for shell commands
• Thinking — thinking/reasoning level configuration