Skip to main content
Templates are role-specific starting points for agents. They live in templates/ and get seeded into the gateway’s local git repo as template/<name> branches on first boot.

​
Template files

FilePurpose
agent.jsonRuntime metadata: slug, name, description, team, capabilities, browser color
IDENTITY.mdRole, voice, and domain behavior
SOUL.mdGoals and non-negotiables
USER.mdOwner profile placeholders (filled at provision time)
MEMORY.mdStarting long-term context
TOOLS.mdTool-use guidance
HEARTBEAT.mdMemory maintenance guidance (scheduled work now handled by Routines)
AGENTS.mdAgent-specific instructions
skills/Reusable procedures and scripts
Key scripts in skills/hq/scripts/:
ScriptPurpose
hq_skill_upsert.pyCreate or update agent-scoped skills with auto-embedding and junction linking
hq_search_docs.pySemantic + full-text search across knowledge items
hq_create_doc.pyCreate a new knowledge item (page or skill)
hq_update_doc.pyUpdate an existing knowledge item
hq_inbox_process.pyProcess background inbox items
hq_claim_task.pyClaim and start working on a task

​
How provisioning works

When you create an agent, HQ forks the selected template branch into the agent’s personal branch, then patches identity fields (slug, name, emoji, channel).

​
Model resolution at provision time

The model field in agent.json is optional. At provision time, add-agent.sh resolves the agent’s model using this cascade:
  1. CLI argument — if the provision command payload includes model, use it
  2. Template’s agent.json — if the template specifies a model, use it
  3. Gateway default — the workspace default from Settings → Connections
  4. First connected model — detected from openclaw models status
After provisioning, you can change the model at any time from the agent detail page → Model section. Changes take effect on the next session without a gateway restart.
To create a custom template, copy templates/default/ to templates/your-role/, edit the identity files, add role-specific skills, and rebuild the templates index. See Agents → Writing a new template for the full walkthrough.