On this page
On this page
CLI commands
Claws
openclaw claws
A Claw 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 Claw to manage. Adding the same Claw 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 Claw status, update, remove, or export commands. To use a newer release, Add it as another agent.
Enable Claws in Settings → Labs before adding one. On a headless installation, set
gateway.controlUi.experimental.claws to true in OpenClaw config.
Authoring and inspecting local Claw packages do not require the Labs toggle.
The CLI accepts a local package directory, CLAW.md, or grouped JSON manifest.
Publishing and searching Claws through ClawHub use the separate registry
surface. The Control UI can browse official and community Claws from Agents,
with each Claw attributed to its publisher.
Create with an agent
With Claws enabled in Labs, choose Create a Claw from an agent's settings,
the chat companion rail, or the agent's left-sidebar context menu. The action
sends the bundled /skill create-claw command into that agent's existing main
chat. The agent proposes portable behavior with an input, job, output, and
authority boundary, writes a private draft, and returns a review link in the
same conversation. It does not create or fork a session. This flow currently
requires a workspace on the Gateway host.
The review link opens a sectioned modal with the exact archive files and declared skill, plugin, MCP, and automation requirements. Change the name or description and uncheck any optional workspace file or requirement before publishing. Ask for changes returns to the same chat; inspect the rebuilt review 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. Review shows the personal publisher
and scoped package name. Publish to ClawHub uploads that exact reviewed
artifact; changing the selection or publisher requires another review. An agent
turn cannot authorize this step. The chat links to a submitted package and
marks public discovery as pending security review.
After ClawHub makes it public, others can discover it and Add it as an ordinary agent.
Author locally
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.
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:
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.
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:
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 chat and starts with "What can you do?" after a successful Add.
--dry-run --json remains available for automation or offline 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.
Add reuses matching shared dependencies, installs missing requirements, creates the agent and its workspace, and assigns its automations. An existing agent or workspace is never overwritten. If Add fails, inspect the specific error and retry after resolving it; newly created resources are cleaned up where safe, while resources that existed before Add are left alone.
Remove the agent
Deleting an agent added from a Claw 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 Claw ownership record or reverse-install operation.
Command reference
| Command | Purpose |
|---|---|
claws create [path] |
Create a minimal local Claw project. |
claws validate [path] |
Validate project inputs and package contents. |
claws dev [path] |
Build and preview locally without mutation. |
claws build [path] --out <tgz> |
Build a deterministic package artifact. |
claws inspect <source> |
Inspect a package or grouped manifest. |
claws 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.
