<!-- source: https://deepwiki.com/openclaw/openclaw/3.2-system-prompt-and-context -->

# System Prompt & Context

- docs/automation/index.md
- docs/concepts/agent-workspace.md
- docs/concepts/context.md
- docs/concepts/soul.md
- docs/concepts/system-prompt.md
- docs/gateway/config-agents.md
- docs/gateway/heartbeat.md
- docs/help/faq.md
- docs/nodes/camera.md
- docs/reference/rich-output-protocol.md
- docs/reference/token-use.md
- docs/start/openclaw.md
- packages/gateway-protocol/src/schema/agents-models-skills.test.ts
- scripts/tsdown-build.mjs
- src/agents/agent-bundle-mcp-materialize.ts
- src/agents/agent-bundle-mcp-runtime.test.ts
- src/agents/agent-bundle-mcp-runtime.ts
- src/agents/agent-bundle-mcp-tools.materialize.test.ts
- src/agents/agent-bundle-mcp-types.ts
- src/agents/agent-tools-agent-config.exec.test.ts
- src/agents/agent-tools.create-openclaw-coding-tools.test.ts
- src/agents/agent-tools.ts
- src/agents/bootstrap-files.test.ts
- src/agents/embedded-agent-helpers/bootstrap.ts
- src/agents/embedded-agent-runner/compact.hooks.test.ts
- src/agents/embedded-agent-runner/compact.queued.ts
- src/agents/embedded-agent-runner/compaction-runtime-context.test.ts
- src/agents/embedded-agent-runner/compaction-runtime-context.ts
- src/agents/embedded-agent-runner/effective-tool-policy.ts
- src/agents/embedded-agent-runner/run/attempt-tool-construction-plan.test.ts
- src/agents/embedded-agent-runner/run/attempt-tool-construction-plan.ts
- src/agents/embedded-agent-runner/run/attempt.prompt-helpers.ts
- src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts
- src/agents/system-prompt.test.ts
- src/agents/system-prompt.ts
- src/agents/test-helpers/fast-openclaw-tools.ts
- src/agents/tool-catalog.test.ts
- src/agents/tool-catalog.ts
- src/agents/tool-policy-audit.ts
- src/agents/tool-policy-pipeline.test.ts
- src/agents/tool-policy-pipeline.ts
- src/agents/tools-effective-inventory.test.ts
- src/auto-reply/reply/agent-runner-memory.test.ts
- src/auto-reply/reply/agent-runner-memory.ts
- src/auto-reply/reply/commands-context-report.test.ts
- src/cli/mcp-cli.test.ts
- src/cli/mcp-cli.ts
- src/cli/update-cli/plugin-payload-validation.test.ts
- src/cli/update-cli/plugin-payload-validation.ts
- src/cli/update-cli/post-core-plugin-convergence.test.ts
- src/cli/update-cli/post-core-plugin-convergence.ts
- src/commands/doctor-plugin-registry.test.ts
- src/commands/doctor-plugin-registry.ts
- src/commands/doctor/shared/active-tool-schema-warnings.test.ts
- src/commands/doctor/shared/active-tool-schema-warnings.ts
- src/config/mcp-config.ts
- src/config/types.agent-defaults.ts
- src/config/zod-schema.agent-defaults.ts
- src/flows/doctor-core-checks.runtime-errors.test.ts
- src/flows/doctor-core-checks.runtime.test.ts
- src/flows/doctor-core-checks.runtime.ts
- src/infra/heartbeat-runner.model-override.test.ts
- src/plugins/channel-catalog-registry.test.ts
- src/plugins/channel-catalog-registry.ts
- src/plugins/installed-plugin-index-record-reader.ts
- src/plugins/installed-plugin-index-records.test.ts
- src/plugins/installed-plugin-index-records.ts
- src/plugins/installed-plugin-index-store.ts
- src/plugins/plugin-peer-link.test.ts
- src/plugins/plugin-peer-link.ts
- src/plugins/stale-local-bundled-plugin-install-records.test.ts
- src/plugins/stale-local-bundled-plugin-install-records.ts
- test/scripts/tsdown-build.test.ts
- ui/src/ui/views/config-quick.test.ts
- ui/src/ui/views/config-quick.ts

This page documents how OpenClaw constructs the system prompt for each agent run, including modular sections, prompt modes, bootstrap file injection, and dynamic context assembly. For information about the agent execution pipeline that uses this prompt, see [Execution Pipeline](https://github.com/openclaw/openclaw/blob/fbdf5937/Execution Pipeline)

## Overview

OpenClaw builds a custom system prompt for every agent run instead of using a static template. The prompt is assembled from modular sections based on configuration, session state, and runtime context. The construction process is primarily handled by the `buildAgentSystemPrompt` function [src/agents/system-prompt.ts111](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L111-L111)

The prompt assembly integrates with plugin hooks and provider-specific transforms to ensure the model has the necessary instructions for tool use and persona embodiment. This logic is crucial for both the primary agent runner [src/auto-reply/reply/agent-runner-memory.ts86-91](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L86-L91) and sub-agent specific contexts [src/agents/system-prompt.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L6-L6)

Standing orders are governed by `AGENTS.md`, which defines repo-root rules and hard policies that the agent must internalize before performing work [docs/gateway/config-agents.md66](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L66-L66)

**Sources:** [src/agents/system-prompt.ts11-13](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L11-L13) [src/auto-reply/reply/agent-runner-memory.ts86-91](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L86-L91) [docs/gateway/config-agents.md66](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L66-L66)

## System Prompt Assembly Flow

The construction of the system prompt involves resolving runtime parameters, invoking plugin hooks, and assembling modular text blocks. The execution pipeline initiates this by gathering all necessary context to build the prompt string.

### Diagram: System Prompt Assembly Flow

Title: System Prompt Assembly Flow

```

```

**Sources:** [src/auto-reply/reply/agent-runner-memory.ts46-48](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L46-L48) [src/agents/system-prompt.ts111-150](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L111-L150) [src/agents/system-prompt.ts25-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L25-L28)

## Prompt Modes

OpenClaw supports three prompt modes defined in `src/agents/system-prompt.ts`. These control which sections are included in the system prompt to optimize token usage and maintain cache stability [src/agents/system-prompt.ts55-60](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L55-L60)

The `minimal` mode is specifically tailored for sub-agents, as seen in `buildSubagentSystemPrompt`, which focuses on task execution rather than persona [src/agents/system-prompt.test.ts6](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.test.ts#L6-L6)

**Sources:** [src/agents/system-prompt.ts55-60](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L55-L60) [src/agents/system-prompt.test.ts125-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.test.ts#L125-L130)

## Modular Sections & Bootstrap Injection

The system prompt is assembled from discrete sections. OpenClaw prioritizes specific files from the workspace, injecting them into the prompt based on a defined order [src/agents/system-prompt.ts63-71](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L63-L71)

### Section Priority (CONTEXT_FILE_ORDER)

Files are sorted using a priority map to ensure foundational instructions appear first [src/agents/system-prompt.ts63-71](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L63-L71):

1. agents.md (10) : Core agent guidelines and standing orders.
2. soul.md (20) : Agent personality, embodiment, and tone.
3. identity.md (30) : Specific identity/persona constraints.
4. user.md (40) : User-specific preferences and history.
5. tools.md (50) : Manual tool usage instructions.
6. bootstrap.md (60) : Initial workspace setup instructions.
7. memory.md (70) : Context related to the memory system.

### Dynamic Context Injection

OpenClaw injects turn-scoped instructions based on the trigger. Files like `heartbeat.md` are treated as dynamic context [src/agents/system-prompt.ts73](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L73-L73)

The injection behavior is configurable via `agents.defaults.contextInjection` [docs/gateway/config-agents.md88-90](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L88-L90):

- "always" : Inject on every turn.
- "continuation-skip" : Skips re-injection on safe continuation turns to save tokens docs/gateway/config-agents.md 92
- "never" : Disables workspace bootstrap injection entirely docs/gateway/config-agents.md 93

### Sub-Agent Delegation

In `full` mode, if the agent has the `sessions_spawn` tool, a specific **Sub-Agent Delegation** section is added [src/agents/system-prompt.ts86-92](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L86-L92) This instructs the agent to:

- Act as a responsive coordinator src/agents/system-prompt.ts 98
- Delegate expensive tasks like shell commands or web browsing src/agents/system-prompt.ts 101
- Use sessions_yield to wait for child results instead of polling src/agents/system-prompt.ts 104-105

**Sources:** [src/agents/system-prompt.ts63-71](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L63-L71) [src/agents/system-prompt.ts86-112](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L86-L112) [docs/gateway/config-agents.md88-102](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L88-L102)

## Personality & Context Maintenance

### SOUL.md & Identity

`SOUL.md` provides the agent's core personality. OpenClaw also injects the current model identity into the runtime prompt so the agent knows its own capabilities [src/agents/system-prompt.test.ts111-118](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.test.ts#L111-L118)

### Diagram: Natural Language Space to Code Entity Space

Title: Context Resolution Mapping

```

```

**Sources:** [src/agents/system-prompt.ts63-71](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L63-L71) [src/agents/system-prompt.test.ts111-123](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.test.ts#L111-L123) [src/auto-reply/reply/agent-runner-memory.ts25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L25-L25)

## Cache Stability & Normalization

To maximize the efficiency of model-side prompt caching, OpenClaw employs several strategies to keep the system prompt stable.

1. Stable Prefix Caching : The stablePromptPrefixCache stores generated prompt prefixes src/agents/system-prompt.ts 115
2. Boundary Markers : The SYSTEM_PROMPT_CACHE_BOUNDARY is used to separate stable instructions from volatile session-specific data src/agents/system-prompt.ts 48
3. Sanitization : Content is cleaned using sanitizeContextFileContentForPrompt to remove restricted strings that might trigger model policy rejections src/agents/system-prompt.ts 160-164

### Diagram: Context Data Flow

Title: Context Injection & Sanitization Data Flow

```

```

**Sources:** [src/agents/system-prompt.ts26-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L26-L28) [src/agents/system-prompt.ts115-135](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L115-L135) [src/agents/system-prompt.ts160-165](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/system-prompt.ts#L160-L165)

## Compaction & Context Maintenance

As sessions grow, the context engine must manage the prompt's size.

1. Context Budgets : OpenClaw splits context budgets by subsystem. agents.defaults.bootstrapMaxChars (default 20,000) and bootstrapTotalMaxChars (default 60,000) control workspace file injection docs/gateway/config-agents.md 104-123
2. Startup Context : On reset or startup, a specific prelude is injected, controlled by agents.defaults.startupContext , which includes recent daily memory files docs/gateway/config-agents.md 204-221
3. Memory Flush : When thresholds are hit, a memory flush can be triggered to move transcript details into permanent storage src/auto-reply/reply/agent-runner-memory.ts 150-161

**Sources:** [docs/gateway/config-agents.md104-123](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L104-L123) [docs/gateway/config-agents.md204-221](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/gateway/config-agents.md?plain=1#L204-L221) [src/auto-reply/reply/agent-runner-memory.ts150-161](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L150-L161)
