Overview
The system prompt is the core instruction that guides AI agent behavior. OpenClaw does not use static prompt templates. Instead, it dynamically constructs system prompts through the buildAgentSystemPrompt() function. This function accepts over 15 parameter types and generates highly customized prompts based on the current channel, user role, available tools, and session context.
The buildAgentSystemPrompt() Mechanism
This function is the core builder of OpenClaw's system prompts. Every time a new agent session is created, the system calls this function to generate a system prompt suited to the current context. Since the Pi SDK is directly embedded (rather than called as a subprocess), this construction process happens within the same runtime with no serialization overhead.
Parameter Type Overview
The main parameter types supported by buildAgentSystemPrompt() include:
- channelType: Current channel type (Discord / Telegram / Slack / WhatsApp)
- channelId: Channel unique identifier
- userId: Current user ID
- userRole: User role (admin, regular user, guest, etc.)
- availableTools: List of currently available tools
- toolDescriptions: Detailed tool description information
- sessionHistory: Session history summary
- customInstructions: User-defined custom instructions
- languagePreference: Language preference settings
- responseFormat: Expected response format
- safetyPolicy: Safety policy configuration
- knowledgeBase: Knowledge base references
- extensionPrompts: Prompt fragments from loaded extensions
- timeContext: Time context (timezone, current time)
- platformConstraints: Platform-specific constraints (e.g., message length limits)
- memoryContext: Persistent memory context
Dynamic Customization by Channel
The most important dynamic dimension of the system prompt is channel adaptation. Different platforms have different interaction norms and technical constraints:
Discord Channel
System prompts for Discord include: embed message format instructions, Markdown rendering rules, emoji usage guidance, thread interaction norms, and a reminder about the 2000-character message length limit.
Telegram Channel
In the Telegram environment, the system prompt adds: inline keyboard interaction instructions, HTML formatting rules (Telegram uses HTML rather than full Markdown), file sending capability descriptions, and the 4096-character message limit.
Slack Channel
Slack system prompts include: Block Kit format instructions, thread reply norms, distinction between app messages and user messages, and workspace-related contextual information.
WhatsApp Channel
In WhatsApp scenarios, the following are injected: concise reply style instructions, limited formatting support descriptions, and media message handling methods.
Custom Instruction Layers
Beyond the system-generated content, administrators and users can inject custom instructions at multiple levels:
Global Instructions
Global instructions set in the OpenClaw configuration file apply to all channels and all users. This is typically where you place the AI agent's core persona, behavioral norms, and universal safety policies.
Channel-Level Instructions
Each channel can have independent custom instructions. For example, a technical support channel can have domain knowledge and troubleshooting procedures injected, while a casual chat channel can set a more relaxed conversation style.
User-Level Instructions
Individual users can set their own preference instructions, such as language preferences and response verbosity. These instructions are merged into the final system prompt during the construction process.
Extension Prompt Integration
When OpenClaw loads extensions, each extension can provide its own prompt fragments. buildAgentSystemPrompt() collects these fragments and merges them into the appropriate position within the system prompt.
For example, an image generation extension might inject a prompt fragment like: "When the user requests image generation, use the image_generate tool. Descriptions should be in English. Style parameters support realistic, anime, sketch, etc."
This design ensures that extensions not only provide tool capabilities but also guide the AI in using those tools correctly.
Session Context Awareness
buildAgentSystemPrompt() also references the current session state:
- Session length: In long conversations, summary context may be added
- Recent topics: Prompt emphasis may be fine-tuned based on conversation topics
- JSONL persistence state: Context is recovered from session persistence storage, including history summaries processed through compaction
Debugging Prompts
Developers can enable debugSystemPrompt: true in the configuration, which outputs the fully constructed system prompt in the logs. This is very useful for debugging unexpected AI behavior — you can see exactly what instructions the AI received.
You can also access the system prompt snapshot for the current channel through the API endpoint /api/debug/system-prompt, making it convenient to inspect prompt content without checking logs.
Best Practices
- Keep it concise: Custom instructions at each level should not be too long, to avoid diluting the effectiveness of core instructions
- Avoid conflicts: Instructions at different levels may contradict each other. Priority order is: safety policy > global instructions > channel instructions > user instructions
- Test and verify: After modifying prompts, use debug mode to verify the final constructed result
- Version control: Include custom instructions in version control to track change history
Summary
buildAgentSystemPrompt() is the core mechanism behind OpenClaw's intelligent channel adaptation. Through dynamic combination of over 15 parameter types, each conversation receives a tailored set of system instructions, enabling the AI agent to deliver the best interaction experience across different platforms and scenarios.