On this page
On this page
CLI commands
Templates
openclaw templates
A Template is a portable setup for a new OpenClaw agent. It can include agent instructions, workspace files, skills, plugins, MCP servers, and automations. Add is a one-way action: it creates an ordinary agent and installs its requirements. It does not create an installed Template to manage. Adding the same Template again creates another agent.
After Add, manage the agent with agent commands, its automations with cron commands, and shared dependencies with their ordinary plugin or MCP controls. There are no Template status, update, remove, or export commands. To use a newer release, Add it as another agent.
Enable Templates in Settings → Labs before adding one. On a headless installation, set
gateway.controlUi.experimental.templates to true in OpenClaw config.
Authoring and inspecting local Template packages do not require the Labs toggle.
templates add accepts a ClawHub package name, a canonical local package directory,
or CLAW.md with YAML frontmatter. Other source-reading commands remain local-only.
Packages must declare package.json.openclaw.template as a safe package-relative
path whose filename is CLAW.md, such as CLAW.md or nested/CLAW.md. The obsolete
openclaw.claw selector and JSON Template manifests are rejected, including in downloaded archives.
CLAW.md, package.json, and OpenClaw YAML profiles must contain valid UTF-8.
If inspection reports an encoding error, re-encode the source file as UTF-8 and retry;
Add refuses it before creating an agent or workspace.
Publishing and searching Templates through ClawHub use the separate registry
surface. The Control UI can browse official and community Templates from Pages → Templates at /templates
when Templates is enabled in Settings → Labs.
Create with an agent
Ask the agent, “create a new template from this agent.” The bundled
create-template skill prepares a request-specific private draft and opens
review in that same conversation. No sidebar setup or special command is
required. The agent proposes portable behavior with an input, job, output, and
authority boundary; it does not publish, return a review link, or create or
fork a session. Review requires Templates enabled in Labs, an active administrator
Control UI connection, and a workspace on the Gateway host. If review is unavailable,
the proposal stays private.
The optional Create Template action in the agent's left-sidebar row menu still invokes the same skill in that agent's existing main chat. Pinned agents keep this action in a focused row menu.
The review modal shows the exact archive files and declared skill, plugin, MCP, and automation requirements. The Name field is the new agent's display name, defaulted to readable title case; it does not change the package slug used as the Template's registry identity. Change the name or description and uncheck any optional workspace file or requirement before publishing. Ask for changes returns to the same chat; review the rebuilt package after the agent revises the draft. The package includes only newly authored proposal contents; it does not copy the source workspace, memories, or raw conversations. Known private paths and credential-like text are rejected. Review the remaining text for personal facts and private context.
Sign in with clawhub login on the Gateway host. Publish to ClawHub uploads
the exact reviewed artifact using that account; changing the selection
requires another review. The editable Name is the agent display name; the
ClawHub package slug and authenticated publisher are separate identities. An
agent turn cannot authorize publication. After submission, a dismissing
notification confirms that publication is pending security review and links
to the Template's ClawHub page.
After ClawHub makes it public, others can discover it and Add it as an ordinary agent.
Author locally
openclaw templates draft <workspace> --json initializes an empty private
proposal in that workspace and returns its unique draftId and path. It does
not copy source files, start a model turn, contact ClawHub, or publish. Each
invocation creates a distinct proposal; retain the returned ID instead of
searching for a latest draft. The bundled skill uses this command when a chat
request did not arrive with a UI-created draft.
Create a minimal project, validate its inputs, preview it without mutation, and build an immutable package artifact:
A package contains package.json, CLAW.md, and any files selected by its
manifest. create writes only package.json and CLAW.md and refuses to merge
into a nonempty directory. Project validation rejects package scripts and
lifecycle hooks. dev builds the same package artifact and checks its Add
requirements locally without installing packages, contacting ClawHub,
starting an agent turn, enabling automations, or changing OpenClaw state.
Requirements needing online preflight appear as blockers. build creates a
deterministic .tgz and refuses to overwrite an existing file.
validate and build accept a project-directory symlink and resolve the
canonical project root. Manifest confinement and managed source-file checks
remain unchanged.
For create, omit --name and --agent-id to use default identities. Explicitly
empty values are invalid and fail before project files are written.
A minimal package.json identifies the package and its manifest:
CLAW.md starts with YAML frontmatter. Its Markdown body becomes the new
agent's SOUL.md:
categories is optional. Declare one to three distinct lowercase slugs for
catalog discovery; the receiving registry decides which category names it
accepts. Categories do not change the agent's runtime behavior.
OpenClaw automatically discovers the optional profiles/openclaw.yml file.
No manifest pointer is required. Other harnesses may discover their own
conventional profile, such as profiles/codex.yml, without changing the
portable manifest.
The older metadata.openclaw.config pointer is deprecated but still read, so
packages published against it keep working. Reading one reports a
deprecated_openclaw_profile_pointer warning; move that file to
profiles/openclaw.yml and remove the metadata entry. A pointer that is not a
package-relative .yml/.yaml path is rejected, and a pointer that references
a different file while profiles/openclaw.yml also exists is rejected as a
conflict.
A package may add named bootstrap files and other workspace files from package-relative sources. These go into the new agent's dedicated workspace:
An optional package-root BOOTSTRAP.md supplies first-run instructions.
The package may also declare exact ClawHub skill and plugin requirements,
MCP servers, and scheduled automations:
Use automations for scheduled work. Older published manifests using cronJobs
remain readable and are normalized to automations. Declaring both keys is an
error; move the declarations to automations and remove cronJobs.
Environment values remain unresolved references; never package credentials. Shared plugins and MCP servers must match existing declarations exactly or Add reports the conflict without replacing them. Plugin and skill trust warnings require explicit consent. Automations are assigned to the new agent. If a declared plugin still needs setup, a referenced environment variable is missing, or an OAuth MCP server is not authorized, Add creates the declared automations paused. Their schedules, prompts, and imported scratch stay intact. Connect the requirement through its ordinary plugin or MCP controls, then enable the jobs through the agent's automation controls; Add does not create substitute routines or automatically enable paused jobs later.
Older packages may declare agent.heartbeat in the OpenClaw profile or include
HEARTBEAT.md. Add converts those inputs into ordinary interval automations
and private job scratch instead of installing heartbeat configuration. Legacy
tasks: entries become separate automations, and the remaining checklist stays
in the monitor's scratch. An every: 0m declaration stays disabled.
The Add review shows each converted job with its interval and owner delivery;
existing cron schedules and none or last-channel delivery keep their meaning.
Gateway review responses represent interval schedules as { everyMs }, where
everyMs is a positive integer, and
owner delivery as owner, alongside the existing { cron, timezone } schedules
and none or last-channel delivery variants.
Add creates a job disabled until its imported scratch is saved and verified. If scratch import conflicts with another edit, or its write cannot be confirmed, Add reports a partial result and keeps the new agent and jobs for inspection. Check their scratch and enabled state before retrying; Add does not overwrite concurrent edits to make the import succeed.
OpenClaw discovers optional harness settings from profiles/openclaw.yml.
Those settings can refine the agent's tools, sandbox, memory search, and
extension requirements, but cannot set a model, provider, credentials, or
named delegate agents. Host policy still constrains every grant. Foreign
harness profiles are ignored by OpenClaw. A released older
metadata.openclaw.config profile pointer is still read with a deprecation
warning; new packages should use the conventional profile path.
Package and workspace paths must stay inside the package root. Manifests are limited to 1 MiB, package metadata to 256 KiB, and workspace files have per-file and aggregate limits. Selected files become package content, so review them for secrets before building or publishing.
Inspect and Add
Inspect a source before using it:
Add it to create a new ordinary agent:
Add a published ClawHub Template directly, or preview the same flow first:
A registry name resolves the latest published release to an exact version and
immutable artifact digest before planning. OpenClaw uses its existing registry
trust checks, verifies the downloaded artifact, and safely extracts it under
bounded package limits. The extracted source is temporary and is cleaned up
after planning or Add; it is not an installed Template lifecycle. An existing
local path takes precedence over a registry name; use ./name to make a local
source explicit.
Registry previews require network access but do not create an agent, workspace,
installed dependency, or retained Template source. Review the exact version,
digest, requirements, and trust warnings in --dry-run --json output. A warned
Template release requires --acknowledge-clawhub-risk when adding it. Template
approval never approves its skill or plugin dependencies: their existing trust
acknowledgments and --accept-capabilities checks still apply independently.
Each Add chooses an unused agent ID. The CLI reports that ID so you can open or configure the agent afterward. The Control UI opens the new agent's pending chat immediately. Sending becomes available when its instruction files, canonical conversation, and active runtime are ready, while remaining setup continues. The first assistant response is a normal personality/SOUL greeting, not a saved canned greeting or a message sent on your behalf. Later setup failure retains the exposed agent and conversation; completion does not replace an existing draft.
The installer shows a card for each newly installed plugin and an automation-created notice as each routine is added. Paused routines stay paused until their setup prerequisites are ready. Actual installation failures appear in the plugin card or a concise automation-failed notice; continue setup in the same agent. Successful skill and MCP setup, absent optional files, and empty categories stay silent. There is no final setup receipt or second model recap. Declared package bootstrap still follows shared setup; MCP configuration alone does not prove a working connection.
--dry-run --json remains available for automation or local-source inspection.
--agent-id and --workspace override the default destination with an
unused ID or new path. Ordinary Add does not require a separate plan or
review token. Exceptional trust warnings can still require explicit consent.
For add and dev, an explicitly empty --agent-id is invalid. Omit the option
to use the default unused ID.
Gateway Add review responses describe schedules as either { cron, timezone }
or { everyMs }, where everyMs is a positive integer in milliseconds. Delivery
values are none, last-channel, or owner.
The CLI Add path requires exclusive offline state ownership; it refuses to run
while a Gateway owns that state. Use the Control UI to Add through a running
Gateway. Offline Add uses the same session, local agent runtime, and scheduler
owners without starting scheduled execution. --json suppresses conversational
terminal output but keeps the ordinary conversation and per-result install notices.
Add reuses matching shared dependencies, installs missing requirements, and assigns the declared automations. An existing agent or workspace is never overwritten. If Add fails before exposing the agent, newly created resources are cleaned up where safe; preexisting resources remain untouched. If the result says the agent was retained, continue in that agent and inspect the specific error instead of adding another copy.
Remove the agent
Deleting an agent added from a Template is the same as deleting any other agent:
The ordinary agent deletion flow removes the agent's dedicated workspace, including its local instructions and skills, and automations assigned to that agent. It also removes files or automations the user added later to that agent. Shared plugins, MCP servers, and other host-level integrations remain installed; remove them separately through their ordinary controls when no longer needed. There is no Template ownership record or reverse-install operation.
Command reference
| Command | Purpose |
|---|---|
templates draft <workspace> |
Initialize a private proposal without publishing. |
templates create [path] |
Create a minimal local Template project. |
templates validate [path] |
Validate project inputs and package contents. |
templates dev [path] |
Build and preview locally without mutation. |
templates build [path] --out <tgz> |
Build a deterministic package artifact. |
templates inspect <source> |
Inspect a canonical package or CLAW.md. |
templates add <source> |
Create a new agent and install its requirements. |
Use --json for experimental machine-readable output. Validation errors,
blocked requirements, and failed additions exit 1.
Human-readable reports sanitize terminal control characters in Template fields
and project paths. --json retains the original field values for machine processing.
