openclaw-mission-control/backend/templates/README.md

Backend Templates (Product Documentation)

This folder contains the Markdown templates Mission Control syncs into OpenClaw agent workspaces.

• Location in repo: backend/templates/
• Runtime location in backend container: /app/templates
• Render engine: Jinja2

What this is for

Use these templates to control what an agent sees in workspace files like:

• AGENTS.md
• HEARTBEAT.md
• TOOLS.md
• IDENTITY.md
• USER.md
• MEMORY.md
• LEAD_PLAYBOOK.md (supplemental lead examples/reference)

When a gateway template sync runs, these templates are rendered with agent/board context and written into each workspace.

How rendering works

Rendering configuration

Defined in backend/app/services/openclaw/provisioning.py (_template_env()):

• StrictUndefined enabled (missing variables fail fast)
• autoescape=False (Markdown output)
• keep_trailing_newline=True

Context builders

• Board agent context: _build_context()
• Main agent context: _build_main_context()
• User mapping: _user_context()
• Identity mapping: _identity_context()

Sync entry points

API

POST /api/v1/gateways/{gateway_id}/templates/sync

• Router: backend/app/api/gateways.py (sync_gateway_templates)
• Service: backend/app/services/openclaw/provisioning_db.py

Script

backend/scripts/sync_gateway_templates.py

Example:

python backend/scripts/sync_gateway_templates.py --gateway-id <uuid>

Files included in sync

Default synced files are defined in:

• backend/app/services/openclaw/constants.py (DEFAULT_GATEWAY_FILES)

Main-agent template mapping is defined in:

• backend/app/services/openclaw/constants.py (MAIN_TEMPLATE_MAP)

HEARTBEAT.md selection logic

HEARTBEAT.md is selected dynamically:

• Board lead -> HEARTBEAT_LEAD.md
• Non-lead agent -> HEARTBEAT_AGENT.md

See:

• HEARTBEAT_LEAD_TEMPLATE, HEARTBEAT_AGENT_TEMPLATE in constants
• _heartbeat_template_name() in provisioning

Template variables reference

Core keys (all templates)

• agent_name, agent_id, session_key
• base_url, auth_token, main_session_key
• workspace_root

User keys

• user_name, user_preferred_name, user_pronouns, user_timezone
• user_notes, user_context

Identity keys

• identity_role, identity_communication_style, identity_emoji
• identity_autonomy_level, identity_verbosity, identity_output_format, identity_update_cadence
• identity_purpose, identity_personality, identity_custom_instructions

Board-agent-only keys

• board_id, board_name, board_type
• board_objective, board_success_metrics, board_target_date
• board_goal_confirmed, is_board_lead
• workspace_path

OpenAPI role tags for agents

Agent-facing endpoints expose role tags in OpenAPI so heartbeat files can filter operations without path regex hacks:

• agent-lead: board lead workflows (delegation/review/coordination)
• agent-worker: non-lead board execution workflows
• agent-main: gateway main / cross-board control-plane workflows

Example filter:

curl -s "$BASE_URL/openapi.json" \
  | jq -r '.paths | to_entries[] | .key as $path
    | .value | to_entries[]
    | select((.value.tags // []) | index("agent-lead"))
    | "\(.key|ascii_upcase)\t\($path)\t\(.value.operationId // "-")"'

Safe change checklist

Before merging template changes:

1. Do not introduce new {{ var }} placeholders unless context builders provide them.
2. Keep changes additive where possible.
3. Review both board-agent and MAIN_* templates when changing shared behavior.
4. Preserve agent-editable files behavior (PRESERVE_AGENT_EDITABLE_FILES).
5. Run docs quality checks and CI.
6. Keep heartbeat templates under injected-context size limits (20,000 chars each).

Local validation

Fast check

Run CI-relevant docs checks locally:

make docs-check

Full validation

• Push branch
• Confirm PR checks are green
• Optionally run template sync on a dev gateway and inspect generated workspace files

FAQ

Why did rendering fail after adding a variable?

Because StrictUndefined is enabled. Add that key to _build_context() / _build_main_context() (and related mappers) before using it in templates.

Why didn’t my edit appear in an agent workspace?

Template sync may not have run yet, or the target file is preserved as agent-editable. Check sync status and preservation rules in constants.