Agent Templates System#

Use this skill when working on OpenClaw's built-in Agent Templates feature.

What this system does#

The Agent Templates system lets OpenClaw store reusable agent blueprints in SQLite, edit them in the Control UI, and materialize real agents from those blueprints.

A template can define:

• identity defaults
• included skills
• partial agent config
• workspace files
• memory seeds

From the UI, a user can:

• list templates
• create templates
• edit templates
• delete templates
• create a real agent from a selected template

Core workflow#

1. Read references/implementation.md first.
2. If UI work is involved, also read references/ui-design.md.
3. If you need payload examples, read references/template-schema.md and inspect assets/examples/.
4. When changing behavior, keep storage, gateway methods, and UI state in sync.
5. When validating a bug or feature, test both:
   • template CRUD
   • agent creation from template

Source of truth files#

Read these files in the OpenClaw repo when making code changes:

• src/agents/templates.ts
• src/gateway/server-methods/agent-templates.ts
• ui/src/ui/controllers/templates.ts
• ui/src/ui/views/templates.ts

Important behaviors#

• Templates are stored in SQLite under the OpenClaw state dir.
• Template definitions are normalized before storage/use.
• Creating an agent from a template updates OpenClaw config, creates a workspace, writes identity/workspace files, and seeds memory.
• Included skills are merged with template config and create-time overrides.
• Workspace file paths are constrained to stay inside the target workspace.

Practical guidance#

• Prefer small, composable template definitions.
• Put durable persona/role setup in workspace.files.
• Put starter memory in workspace.memorySeeds.
• Use definition.skills for reusable attached skills.
• Keep UI wording aligned with the underlying JSON schema.
• If the UI allows raw JSON editing, make parser errors user-legible.

Debugging checklist#

• Can agentTemplates.list return the template?
• Does agentTemplates.get return the expected normalized definition?
• Does the UI render the selected template and preserve edits?
• Does agents.createFromTemplate create a non-conflicting agent id?
• Were SOUL.md, IDENTITY.md, AGENTS.md, and any seeded files written as expected?
• Did config get updated with workspace, identity, and merged skills?

References in this skill#

• references/implementation.md — architecture and code map
• references/template-schema.md — practical schema notes and field behavior
• references/ui-design.md — Control UI layout and UX notes
• assets/examples/agent-template-definition.json — example template payload