openclaw
Version:
Multi-channel AI gateway with extensible messaging integrations
646 lines (543 loc) • 29.1 kB
Markdown
---
summary: "Create, add, update, and remove experimental Claw agent packages"
read_when:
- You are authoring or validating a CLAW.md manifest
- You want to preview or add one agent from a Claw
- You need to inspect Claw ownership, drift, or cleanup behavior
title: "Claws"
---
# `openclaw claws`
A Claw is a versioned setup for one OpenClaw agent. It can describe the
agent's portable identity, workspace files, skills, plugins, MCP servers, and
cron jobs. Harness-specific agent settings may be carried in a conventional
package profile. Adding a Claw creates a separate agent; `claws migrate` can
enroll an existing agent without replacing it or moving its workspace.
Claws are experimental. Their schema, command output, and lifecycle may change.
Enable the command surface explicitly:
```bash
export OPENCLAW_EXPERIMENTAL_CLAWS=1
```
For human-readable `claws add`, OpenClaw prints the experimental warning before
changing state. JSON mode keeps stdout machine-readable and identifies the
contract with `"stability": "experimental"`.
The current CLI reads a local package directory, `CLAW.md`, or grouped JSON manifest.
Publishing, searching, and installing whole Claws through ClawHub are a
separate registry track and are not part of this command surface yet.
## Bundled role Claws
The bundled `coordinator`, `researcher`, `writer`, and `reviewer` roles are Claw
sources at `docs/reference/templates/roles/<role>` in a source checkout, with no
`package.json` requirement. Use [`agents add --role`](/cli/agents#role-templates)
or `openclaw claws add docs/reference/templates/roles/<role>` through the
[preview and consent flow](/cli/claws#inspect-and-preview).
[`agents team create`](/cli/agents#agents-team-create) owns delegation wiring;
the role Claws will carry those settings once separate Claw profile support lands.
## Create a Claw package
A package contains `package.json`, a `CLAW.md` manifest, and any conventional
profiles, bootstrap instructions, or portable assets used by that manifest:
```json
{
"name": "@acme/incident-triage-claw",
"version": "1.0.0",
"type": "module",
"openclaw": { "claw": "CLAW.md" }
}
```
`CLAW.md` starts with YAML frontmatter. A non-empty Markdown body is the
portable agent prompt. OpenClaw applies it as the Claw-managed `SOUL.md` for
the new agent:
```md
---
schemaVersion: 1
agent:
id: incident-triage
name: Incident triage
workspace:
bootstrapFiles: {}
packages: []
mcpServers: {}
cronJobs: []
---
# Incident triage
You review incoming incidents, identify severity and ownership, and leave a
concise handoff with evidence.
```
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.
```yaml
schemaVersion: 1
agent:
model:
primary: acme/primary
fallbacks: [acme/fallback]
subagents:
allowAgents: [researcher, writer]
delegationMode: prefer
tools:
allow: [read, write, cron]
deny: [exec]
fs:
workspaceOnly: true
memory:
search:
enabled: true
rememberAcrossConversations: true
sources: [memory, sessions]
```
This profile exists only inside the Claw package. OpenClaw validates and uses it
while inspecting, adding, updating, and exporting that Claw; it is not copied
to the user's normal OpenClaw configuration path. Other harnesses consume the
portable manifest and interpret only their own conventional profile.
`agent.model` selects a required `primary` reference and optional ordered
`fallbacks`. Every reference must use non-empty `provider/model` form; the
`acme` references above are examples to replace with your configured models.
`agent.subagents.allowAgents` lists delegation target agent IDs using the same
lowercase ID rules as the Claw agent. An empty list explicitly grants no
delegation targets. Optional `delegationMode` accepts `suggest` or `prefer`.
Both objects are optional and reject unknown keys.
Add and update plans disclose the model and delegation configuration. Models
absent from the local catalog and targets absent from the local agent roster
produce notices, not blockers. The exact plan consent applies these values as
declared, so a team can be installed one Claw at a time. Configure unavailable
models and install missing targets before using them. `claws dev` checks the
local catalog offline. Status detects changes to either field through agent
configuration drift, and export preserves explicit agent settings without
copying inherited defaults.
The same strict version 1 schema continues to accept grouped JSON manifests.
Grouped JSON discovers the same conventional profile rather than embedding a
second copy of the OpenClaw settings. The remaining schema fragments on this
page use JSON, with equivalent keys available in `CLAW.md` frontmatter.
The OpenClaw package profile may use an explicit `tools.allow` list or select
any built-in tool profile registered by the running OpenClaw version. The
`coding` and `messaging` profiles include the dynamic `bundle-mcp` selector, so
a Claw that selects either profile must also provide a bounded `tools.allow`
intersection. Name any MCP grants as concrete generated tool names such as
`github__list_issues`; the package cannot freeze `bundle-mcp` itself.
Profiles can otherwise be refined with `alsoAllow`, `deny`, and
`tools.fs.workspaceOnly: true`. `tools.allow` cannot be combined with
`alsoAllow`; use a standalone allowlist, as above, when the package needs tools
outside its selected profile. A Claw cannot set `workspaceOnly` to `false` and
weaken host filesystem confinement. A Claw may also set
`memory.search.enabled`, choose the portable `memory` and `sessions` sources,
and opt into cross-conversation memory with `rememberAcrossConversations`.
Declaring the `sessions` source requires that opt-in.
Host policy still constrains these settings, and Claws do not carry custom
profile definitions, providers, credentials, bindings, or local memory paths.
The conventional profile is limited to 256 KiB, must be JSON-compatible YAML, may
not use aliases, anchors, tags, or merge keys, and must be a regular,
non-symlinked, non-hardlinked file inside the package.
An OpenClaw profile may also declare harness-specific extension requirements:
```yaml
schemaVersion: 1
agent: {}
extensions:
- id: incident-tools
kind: plugin
format: claude
source: clawhub
ref: "@acme/incident-tools"
version: 2.0.0
```
`format` asserts the artifact format that OpenClaw must detect (`openclaw`,
`claude`, `codex`, or `cursor`). The canonical plugin preflight resolves the
exact artifact and reports which components the current OpenClaw adapter maps
and which remain unavailable. Missing identity, integrity, format detection, or
adapter identity blocks apply. Extension-backed plugins use the existing
plugin installer and ownership model; they are shared host requirements, not
Claw-owned members or a second package system.
OpenClaw ignores foreign harness profiles during apply. Package integrity still
covers every published package byte, while a development snapshot binds the
portable manifest, bootstrap and workspace sources, and the selected OpenClaw
profile. Status and doctor report adapter mapping drift or unavailable
inspection. Export writes extension-backed plugins to `profiles/openclaw.yml`
and does not duplicate them in the portable `packages` list.
Package and workspace paths must remain inside the package root. Manifests are
limited to 1 MiB, package metadata to 256 KiB, and workspace sources enforce
separate per-file and aggregate limits. Workspace sources also reject symlinked
parents.
The `CLAW.md` body is the preferred portable source for `SOUL.md`; do not also
declare a `SOUL.md` sidecar when the body is non-empty. Other bootstrap files
use named entries, while additional files use package-relative sources and
workspace-relative targets:
```json
{
"workspace": {
"bootstrapFiles": {
"AGENTS.md": { "source": "workspace/AGENTS.md" }
},
"files": [
{
"source": "workspace/reference/policy.md",
"path": "reference/policy.md"
}
]
}
}
```
Additional files are the portable asset mechanism. Authors may organize package
sources under directories such as `assets/`, `schemas/`, `templates/`, and
`examples/`, then map them into the new agent workspace with
`workspace.files`. Apply records those destinations as managed files; update
reconciles unchanged managed assets, and remove preserves modified or
user-owned files.
An optional package-root `BOOTSTRAP.md` supplies conversational first-run
instructions. OpenClaw seeds it into the new agent workspace and records
progress through the native workspace bootstrap state. Once the agent consumes
or removes it, Claw update does not recreate it. Root `BOOTSTRAP.md` therefore
cannot also be declared through `workspace.files`. Claw removal deletes an
unchanged, still-pending package bootstrap after verifying its recorded digest;
it preserves edited bootstrap content and files created during onboarding.
Skills and plugins use exact ClawHub versions:
```json
{
"packages": [
{
"kind": "skill",
"source": "clawhub",
"ref": "incident-triage",
"version": "1.0.0"
},
{
"kind": "plugin",
"source": "clawhub",
"ref": "@acme/audit-plugin",
"version": "2.0.0"
}
]
}
```
The dry run uses the existing skill and plugin preflight paths to resolve the
exact artifact, integrity, and any ClawHub trust warning before consent. The
warning remains visible in the integrity-bound plan. Each requirement is shown
as satisfied, missing-installable, conflicting, or setup-required. The exact
plan consent approves missing installs; OpenClaw completes those canonical
plugin actions before creating the agent or workspace. Apply reuses matching
artifacts and records whether the Claw introduced or referenced each resource.
Plugins remain process-wide OpenClaw capabilities rather than per-agent
installations.
Cron jobs declare scheduled work for the new agent:
```json
{
"cronJobs": [
{
"id": "daily-summary",
"name": "Daily incident summary",
"schedule": { "cron": "0 9 * * *", "timezone": "UTC" },
"session": "isolated",
"message": "Summarize active incidents."
}
]
}
```
Claws use the existing Gateway scheduler and bind created jobs to the new
agent. Before creating jobs during add or update, Claws wait for the target
agent to appear in the Gateway's applied configuration. Preview, provenance,
status, and removal cover those jobs without
changing the behavior of ordinary cron commands. Removal rereads the live job
through the Gateway and preserves it when its owned definition changed after
planning.
MCP declarations use the existing `mcp.servers` configuration model:
```json
{
"mcpServers": {
"statuspage": {
"command": "npx",
"args": ["--yes", "@acme/statuspage-mcp@1.0.0"],
"env": { "STATUSPAGE_TOKEN": "${STATUSPAGE_TOKEN}" }
}
}
}
```
Environment references remain references; Claws do not embed resolved secret
values. A collision-free declaration becomes managed, while an exact existing
or shared declaration is referenced. Preview, provenance, status, export, and
removal follow the same ownership policy as other Claw resources.
## Author locally
Create a minimal project, validate its publishable inputs, preview its complete
OpenClaw add plan offline, and build an immutable package artifact:
```bash
openclaw claws create ./incident-triage
openclaw claws validate ./incident-triage
openclaw claws dev ./incident-triage
openclaw claws build ./incident-triage --out ./incident-triage-1.0.0.tgz
```
`create` writes only `package.json` and `CLAW.md` and refuses to merge into a
nonempty directory. Project validation requires `openclaw.claw` to point to
the root `CLAW.md`, rejects package scripts and lifecycle hooks, discovers a
single unambiguous project root, and reports files excluded from the package.
`dev` validates and builds the same artifact that would be published, then
runs that artifact through the canonical add planner. It does not install
packages, contact ClawHub, start an agent turn, enable schedules, deliver
messages, or modify OpenClaw state. Dependencies that require online preflight
appear as blockers instead of weakening that boundary. Use `--agent-id` or
`--workspace` to preview collision-free local destinations.
`build` writes a deterministic npm-compatible `.tgz` with a `package/` root.
Only package metadata, `CLAW.md`, optional `BOOTSTRAP.md`, the OpenClaw profile,
and sources selected by the manifest are included. Tests, caches, ambient or
unselected credentials, unselected files, prior artifacts, and source-control
state remain outside the package. Selected source bytes are package content, so
authors must not select secret-bearing files. Build refuses to overwrite an
existing artifact, reports its SHA-256 integrity, and re-opens it through the
canonical Claw reader before success.
## Inspect and preview
Validate the source without planning local changes. For OpenClaw profile
extensions, inspect also performs the canonical read-only artifact probe and
reports mapped and unavailable components:
```bash
openclaw claws inspect ./incident-triage.claw.json
```
Preview all proposed lifecycle actions:
```bash
openclaw claws add ./incident-triage.claw.json --dry-run --json
```
The plan reports the derived agent and workspace, every proposed action,
prerequisites, blockers, distinct capability escalations, and a `planIntegrity`
digest. Capability records show the exact package, MCP, scheduled-work, sandbox,
tool, or heartbeat effect. Review the plan before creating the agent:
```bash
openclaw claws add ./incident-triage.claw.json \
--yes \
--plan-integrity <SHA256_FROM_DRY_RUN>
```
`--yes` alone is insufficient. OpenClaw rebuilds the plan and rejects consent
when the source, destination, or live configuration changed after preview. Use
`--agent-id` or `--workspace` during both preview and apply when package
defaults collide with local state. For disposable profiles and parallel validation,
pass an explicit `--workspace`; `OPENCLAW_STATE_DIR` relocates runtime state but
does not change the default workspace location.
Adding a Claw first realizes consented shared plugin requirements, then creates
the new agent and workspace configuration, seeds optional first-run
instructions, writes declared workspace assets, realizes workspace skills, and
records package, MCP, and cron provenance. Existing files are not overwritten,
and retries fail closed when owned content drifted.
With a local Gateway running, Claw add and update apply their plugin requirements
before continuing to the agent, workspace, MCP, and cron phases. One bounded
handoff reloads the affected packages after the package leases have been released;
it does not restart the Gateway or reload unrelated plugins. A live requirement
batch supports at most 64 plugin packages. Normal package, capability, and trust
confirmation still apply.
If installation was saved but runtime activation was not confirmed, the command
reports that distinction and stops before later phases. Inspect the reported
error and preview again before retrying. An exact retry reuses the saved package
and retries activation. Successfully realized shared requirements remain installed
if a later Claw phase fails. Disabled or metadata-only entries remain unevaluated;
their source has not been verified by runtime execution. With no local Gateway,
installation retains the existing restart requirement.
## Inspect installed state
```bash
openclaw claws status
openclaw claws status incident-triage --json
openclaw doctor
```
`status` compares the installed agent and its recorded workspace, package, MCP,
and cron provenance with current state. It also reports whether native
first-run bootstrap remains pending. It reports incomplete installs, missing
resources, and drift without changing local state. `openclaw doctor` adds
Claw-specific diagnostics for incomplete ownership records, unsafe managed
files, and cron jobs that cannot be corroborated with live Gateway inventory.
Claw provenance distinguishes two relationships:
- **Managed:** the Claw introduced and currently manages the resource. It is a
cleanup candidate when unchanged and no conflicting owner remains.
- **Referenced:** the resource existed independently or is shared. Removal
releases this Claw's reference and retains the resource by default.
This is not a reference count. Ordinary plugin, skill, and agent commands keep
their existing behavior; Claws add provenance and guarded lifecycle operations
on top.
## Migrate an existing agent
`claws migrate` enrolls one already configured local agent without creating a
second agent or moving its workspace. It creates a local package under the
OpenClaw state directory, previews the exact profile and existing files that
will become Claw-managed, lists the generated package files, and asks for
confirmation:
```bash
openclaw claws migrate research-agent
```
For automation, inspect the read-only plan and apply only that exact plan:
```bash
openclaw claws migrate research-agent --dry-run --json
openclaw claws migrate research-agent \
--yes \
--plan-integrity <SHA256_FROM_DRY_RUN> \
--json
```
Migration supports Claw v1 agent identity and OpenClaw profile settings, plus
the existing `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `TOOLS.md`, and
`HEARTBEAT.md` prompt files. It fails closed when a setting cannot be
represented faithfully, workspace ownership is ambiguous, a selected file is
unsafe, or likely secret material is detected. Selected files are recorded
with their existing content digests and are not rewritten. `BOOTSTRAP.md`,
credentials, sessions, transcripts, databases, and every other workspace entry
remain local and outside Claw ownership.
Inherited model, subagent allowlist/delegation, heartbeat schedule, sandbox
mode/scope/workspace access, and human-delay defaults are copied into the
generated profile. Host ownership pointers such as `heartbeat.agentId` remain in
OpenClaw config. Other inherited agent defaults that Claw v1 cannot carry,
including provider params, skills, model policy/catalog, or unsupported
heartbeat/sandbox fields and custom compaction settings, block migration with
their setting paths in the diagnostic. An empty compaction placeholder or the
effective `safeguard` default materialized by OpenClaw has no effect beyond the
runtime default and is ignored.
`claws status` and `claws update` use the generated package after migration.
Removing an adopted Claw releases its ownership records while retaining the
pre-existing agent, workspace, local package, credentials, databases, sessions,
and transcripts.
## Update an installed Claw
By default, update uses the source recorded when the Claw was added. Use
`--from` when that source moved or when testing another package directory:
```bash
openclaw claws update incident-triage --dry-run --json
openclaw claws update incident-triage \
--from ./incident-triage-next \
--dry-run --json
```
The plan compares current provenance and live state with the target manifest.
It reports agent, workspace, package, MCP, cron, and ownership changes,
including capability escalations and blockers. Capability escalations have
separate machine-readable records and `!` lines with exact redacted effects in
human output. Resolved package integrity, install identity, trust warnings, and
remaining local setup prerequisites are included. Removing a package declaration
releases this Claw's edge without uninstalling the artifact during update. The eventual
exact `planIntegrity` confirmation binds that disclosed set as well as ordinary
content changes. Hosts may use the same records for a separate dialog or an
aggregate multi-agent review. Apply the exact reviewed plan with explicit
consent:
```bash
openclaw claws update incident-triage \
--yes \
--plan-integrity <SHA256_FROM_DRY_RUN>
```
OpenClaw rebuilds the plan and compare-and-swaps owned state before each
mutation. Removed package declarations release dependency edges without
uninstalling artifacts. Cron changes reread the live scheduler definition and
stop on operator drift. Package installers, source-config writers, and the Gateway scheduler
are not one transaction. If compensation cannot be proven after an external
mutation, OpenClaw reports error code `update_partial` with structured
`status: partial`, preserves uncertain provenance,
and stops. Inspect `claws status`, the affected resource, and `openclaw doctor`;
then preview again before retrying or removing anything.
## Remove an installed Claw
Preview removal before selecting cleanup:
```bash
openclaw claws remove incident-triage --dry-run --json
openclaw claws remove incident-triage \
--yes \
--plan-integrity <SHA256_FROM_DRY_RUN>
```
The default removes eligible managed state and releases referenced state.
Eligible Claw-owned schedules appear once as removal actions. The serving
Gateway also identifies this agent's config-owned heartbeat and Skill Workshop
monitors, including disabled monitors, as removal actions. Ordinary schedules,
imported heartbeat tasks, uncorroborated monitors, and jobs in another scheduler store
remain blockers.
Modified files and resources with another current owner are retained or
blocked. The workspace is retained if it contains untracked files or its contents
cannot be fully checked, including when a child directory disappears during cleanup.
Cleanup choices are part of the plan digest; `--yes` never broadens
them. By default, globally installed plugins are retained while this Claw's reference is
released. Removal reports which retained requirements Claw add introduced; use
the ordinary plugin lifecycle separately when you intend to uninstall a
process-wide plugin.
Directories containing another agent's registered database are retained, even
when that database is closed. If removal reports that an agent database is
still open, stop the command or restart the Gateway holding it before retrying.
Preview works offline. Persisted monitor rows remain blockers until the serving
Gateway can verify their ownership. Actual removal requires a running Gateway
with administrator access to the same config, state database, and scheduler
store, even when no scheduled rows remain. The Gateway requests cancellation of consented scheduled work and waits
for its running code to finish before local cleanup. Removing a job row or
receiving its cancellation outcome does not establish that its code has stopped.
After config removal, cleanup also waits for the Gateway to apply that change
and remove the monitors. A database-lease refusal leaves the agent config,
execution approvals, and creation history unchanged.
If cancellation, drainage, or config convergence cannot finish, removal reports
`partial` with `monitor_cleanup_failed` and keeps its deletion fence and cleanup
record. Local files remain intact. Resolve the reported failure, preview again,
and retry removal. The fence prevents new runs and agent recreation until cleanup
finishes; restarting the Gateway does not discard an incomplete removal.
If session cleanup or transcript archive export fails after the agent is removed
from config, removal reports `partial` with `session_cleanup_failed` and retains
its cleanup record. Correct the reported error, preview removal again, and retry
to finish cleanup before recreating the agent.
To remove unchanged Claw-introduced references that have no other current
owner, include `--remove-unused` in both preview and apply. Global plugins are
excluded from this generic cleanup mode. To select exact
referenced resources instead, repeat `--remove-referenced`:
```bash
openclaw claws remove incident-triage \
--dry-run \
--remove-referenced 'plugin:/audit-plugin@2.0.0'
```
Use `--force-referenced` only after reviewing the displayed dependents,
independent owners, and pre-existing origin. It allows selected cleanup despite
those conflicts; it does not skip plan-integrity consent.
For a selected plugin, the serving Gateway withdraws its runtime capabilities
and attempts cleanup before deleting its installed files. The command waits for
runtime application and reports the resulting Gateway generation without
restarting the Gateway. Ownership and artifact changes after preview require a
fresh plan. Cleanup is best effort: warnings appear in the result's `warnings`
list and in human-readable output, without turning a completed removal into a
failed result.
If package cleanup fails, removal reports `partial` with `package_cleanup_failed`
and retains its cleanup record. Earlier removal steps are not rolled back.
A Gateway runtime replacement failure stops the remaining package phase and
reports unattempted packages as retained, alongside earlier outcomes and warnings.
Ordinary package errors continue best-effort cleanup of the other selections.
Resolve the reported failure, preview again, and retry; a lost connection never
causes an automatic local uninstall.
## Export an installed agent
Export creates a new package directory and fails if the destination exists or
managed state has drifted:
```bash
openclaw claws export incident-triage --out ./incident-triage-export --json
```
Use `--bootstrap <path>` to attach an explicitly reviewed Markdown file as the
package-root `BOOTSTRAP.md`. Export re-emits an unchanged, still-pending package
bootstrap automatically. A package bootstrap that drifted in the workspace
(edited, unsafe, or unreadable) fails the export with `bootstrap_drifted`, the
same way managed workspace files fail with `workspace_files_drifted`; pass
`--bootstrap <path>` with a reviewed replacement to export anyway. A bootstrap
the agent already consumed is a completed lifecycle state, so export omits
`BOOTSTRAP.md` instead of failing. The exporter validates the completed package
and removes the new output directory if validation fails. Bootstrap is
package-authored prompt content: do not include credentials, tokens, private
answers, or machine-specific paths. Export does not infer questions, render
personal-data templates, persist answers, or add a separate setup lifecycle.
The result contains `package.json`, canonical `CLAW.md`, and managed workspace
sidecars. Managed `SOUL.md` content is emitted as the `CLAW.md` body when it is
non-empty UTF-8 and the combined document fits the manifest limit. Otherwise,
export retains it as an explicit sidecar so the package remains importable. It
is a portable Claw package, not a whole-instance backup: unrelated agents,
credentials, sessions, and unowned local state are excluded.
## 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>` | Validate a package directory or grouped manifest. |
| `claws add <source>` | Preview or create one new agent and workspace. |
| `claws status [claw-or-agent]` | Report installed state, ownership, and drift. |
| `claws update <claw-or-agent>` | Preview or apply changes from the selected source. |
| `claws remove <claw-or-agent>` | Preview or remove the agent and eligible resources. |
| `claws export <agent> --out <path>` | Create a portable package from an installed agent. |
Use `--json` for experimental machine-readable output.
Successful commands exit `0`. Validation errors, blocked plans, missing
targets, and both `failed` and `partial` mutation results exit `1`. Inspect the
JSON `status` and `error.code` fields to distinguish a failure that made no
change from a partial result that requires `claws status`, `openclaw doctor`,
and a new preview before retrying.
## See also
- [Agents](/cli/agents)
- [Skills](/tools/skills)
- [Plugins](/tools/plugin)
- [Cron jobs](/automation/cron-jobs)
- [MCP configuration](/gateway/config-extensions#mcp)