Prompt Variables Reference

What Are Prompt Variables

When OpenClaw assembles the system prompt before each task, it renders any Jinja2 template expressions in the prompt string. This lets you write system prompts that automatically include current context: today's date, the full list of available tools with their descriptions, the current agent name, or values from your configuration. Without prompt variables, these dynamic values would require constantly editing the system prompt manually.

Built-in Variables

Using Variables in System Prompts

agent:
  system_prompt: |
    You are {{agent_name}}, an AI assistant with access to these tools:

    {{tools}}

    Today's date is {{date}}. Always cite the current date when your
    response refers to recent events.

Variables in system prompts are rendered once at task start, before the first LLM call. They are not re-rendered on each reasoning step. If you need a value that changes during a task (like real-time data), use a tool to fetch it rather than a prompt variable.

Custom Variables

Define your own variables in the config under agent.prompt_vars:

agent:
  prompt_vars:
    company_name: Acme Corp
    output_language: Spanish
    max_response_length: 500 words
  system_prompt: |
    You are a customer service agent for {{company_name}}.
    Always respond in {{output_language}}.
    Keep responses under {{max_response_length}}.

Dynamic Variables via Hooks

For system prompt variables that need to be computed fresh at task start (user-specific context, real-time configuration from a database), use the prompt_var_hook plugin interface. A prompt var hook is a Python function called with the task input before prompt rendering; it returns a dictionary that is merged into the template context. This enables powerful patterns: injecting the current user's permissions into the system prompt, adding company-specific instructions fetched from a config store, or including recently-updated team guidelines.

Prompt Template Best Practices

Always include {{tools}} in your system prompt when you enable tools — without it, the LLM has no way to know what tools are available and won't use them effectively. Always include {{date}} when your tasks involve time-sensitive information. Avoid overly-long system prompts (above 2,000 tokens) — they consume context budget and often dilute the effective instructions; keep prompts focused on the most critical constraints and behaviors.

Test your prompt templates with openclaw config show --expand-prompts to see the fully rendered system prompt before running tasks. This catches template syntax errors and ensures the rendered prompt reads correctly.

Jinja2 Features Available in Prompts

OpenClaw system prompts support a subset of Jinja2 template features beyond simple variable substitution. Conditional blocks allow you to change prompt behavior based on configuration values:

agent:
  system_prompt: |
    You are {{agent_name}}.

    {% if tools %}
    You have access to these tools:
    {{tools}}
    Use tools when you need current information or to perform actions.
    {% else %}
    You do not have access to external tools. Answer from your training knowledge.
    {% endif %}

    {% for constraint in constraints %}
    - {{constraint}}
    {% endfor %}

Available Jinja2 features: variable substitution {{var}}, conditionals {% if %}...{% endif %}, loops {% for %}...{% endfor %}, filters {{var | upper}}, and default values {{var | default("fallback")}}. Avoid complex computed expressions in templates — they make prompts hard to read and debug. Keep templates simple and move complex logic to prompt var hooks.

Debugging Prompt Rendering

If an agent behaves unexpectedly, examine the fully-rendered system prompt to verify that template variables resolved correctly. The debug log includes the complete rendered system prompt at the start of each task — enable DEBUG logging for a test run and search for the event: agent.system_prompt_rendered log entry. The prompt field contains the exact string sent to the LLM, with all variables substituted.

Common prompt variable bugs: a variable name typo that silently renders as an empty string (Jinja2 doesn't error on undefined variables by default — configure agent.strict_template: true to make undefined variables raise errors in your dev environment); a prompt var hook that returns a non-string value formatted unexpectedly; or a custom variable override in an environment-specific config that doesn't take effect because the base config's value is cached.

Localization with Prompt Variables

Prompt variables make localization straightforward. Define language and locale as custom prompt_vars, and reference them in the system prompt: "Always respond in {{language}}. Format dates as {{date_format}}." For a multilingual deployment, set different values for each agent configuration or override via environment variables based on the deployment region. This approach keeps all localization concerns in configuration rather than scattered through multiple system prompts, making it easy to update localization settings consistently across all agents.

Quick Reference Summary

The most commonly used variables in production system prompts are {{agent_name}}, {{tools}}, and {{date}}. Include tools in any agent that has tools enabled — it's the most impactful single variable for tool-using agent effectiveness. Include date for any agent that might be asked about current events, recent developments, or time-sensitive tasks. Use custom prompt_vars for any organization-specific context that changes per deployment but not per task. Use prompt_var_hooks for any context that needs to be fetched dynamically at task execution time.