OpenClaw Claws: Create and Manage Experimental Agent Packages

openclaw claws

A Claw represents a versioned configuration bundle for creating a single new OpenClaw agent. This bundle may define the agent's portable identity, workspace files, skills, plugins, MCP servers, and cron jobs. Harness-specific agent settings can be included through a referenced package profile. Claws do not alter or overwrite any existing agent.

These Claws are considered experimental. Their schema, command output, and lifecycle are subject to change. To enable the command surface, you must do so explicitly:

export OPENCLAW_EXPERIMENTAL_CLAWS=1

The current CLI reads from a local package directory, CLAW.md, or a grouped JSON manifest. Publishing, searching, and installing complete Claws through ClawHub belong to a separate registry track and are not yet available through this command surface.

Create a Claw package

A package consists of package.json, a CLAW.md manifest, and any profiles or workspace sidecars referenced within that manifest:

{
  "name": "@acme/incident-triage-claw",
  "version": "1.0.0",
  "type": "module",
  "openclaw": { "claw": "CLAW.md" }
}

CLAW.md begins with YAML frontmatter. Its Markdown body provides a human-readable description of the Claw and is not used in the agent configuration:

---
schemaVersion: 1
agent:
  id: incident-triage
  name: Incident triage
metadata:
  openclaw.config: profiles/openclaw.yml
workspace:
  bootstrapFiles: {}
packages: []
mcpServers: {}
cronJobs: []
---

# Incident triage

Creates one agent for reviewing and routing incidents.

metadata serves as a string-to-string map for portable consumer hints. The openclaw.config key in OpenClaw points to an optional YAML profile located relative to the package. The exported default is profiles/openclaw.yml; since the pointer is normative, a package may select a different safe relative .yml or .yaml path.

schemaVersion: 1
agent:
  tools:
    profile: coding
    alsoAllow: [cron]
    deny: [exec]
    fs:
      workspaceOnly: true
  memory:
    search:
      enabled: true
      rememberAcrossConversations: true
      sources: [memory, sessions]

This profile exists solely within the Claw package. OpenClaw validates and uses it when inspecting, adding, updating, or exporting that Claw; it is not placed into the user's standard OpenClaw configuration path. Other harnesses may ignore this namespaced metadata key and instead consume the portable manifest fields.

The same strict version 1 schema also accepts grouped JSON manifests. Grouped JSON uses the same metadata.openclaw.config pointer rather than embedding a duplicate of the OpenClaw profile. The remaining schema fragments on this page are shown in JSON, with equivalent keys available in CLAW.md frontmatter.

The OpenClaw package profile may choose any built-in tool profile registered by the running OpenClaw version and then refine it with alsoAllow, deny, and tools.fs.workspaceOnly: true. A Claw cannot set that field to false to weaken host filesystem confinement. tools.allow remains available as an explicit allowlist but cannot be combined with alsoAllow. A Claw may also set memory.search.enabled, select the portable memory and sessions sources, and enable cross-conversation memory with rememberAcrossConversations. Declaring the sessions source requires that opt-in. Host policy still restricts these settings, and Claws do not carry custom profile definitions, providers, credentials, bindings, or local memory paths. The referenced profile is limited to 256 KiB, must be JSON-compatible YAML, cannot use aliases, anchors, tags, or merge keys, and must be a regular, non-symlinked, non-hardlinked file within the package.

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 parent directories.

Workspace files are declared by path and read from package sidecars. Bootstrap files like SOUL.md use named entries; additional files use package-relative sources and workspace-relative targets:

{
  "workspace": {
    "bootstrapFiles": {
      "SOUL.md": { "source": "workspace/SOUL.md" }
    },
    "files": [
      {
        "source": "workspace/reference/policy.md",
        "path": "reference/policy.md"
      }
    ]
  }
}

Skills and plugins use exact ClawHub versions:

{
  "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. Apply installs missing artifacts or reuses matching ones 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:

{
  "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. Preview, provenance, status, and removal cover those jobs without altering 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:

{
  "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.

Inspect and preview

Validate the source without planning local changes:

openclaw claws inspect ./incident-triage.claw.json

Preview all proposed lifecycle actions:

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:

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 creates the new agent and workspace configuration, writes declared workspace files, installs or reuses declared skill and plugin artifacts, and records package, MCP, and cron provenance. Existing files are not overwritten, and retries fail closed when owned content drifted.

Inspect installed state

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 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.

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:

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, and any trust warning 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:

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:

openclaw claws remove incident-triage --dry-run --json
openclaw claws remove incident-triage \
  --yes \
  --plan-integrity <SHA256_FROM_DRY_RUN>

By default, eligible managed state is removed and referenced state is released. Files and resources that have been modified or are owned by another current owner are either kept or prevented from being removed. Cleanup decisions are included in the plan digest, and --yes never expands them. Plugins installed globally are kept while this Claw’s reference is released; use the standard plugin lifecycle separately if you want to uninstall a system-wide plugin.

To delete unchanged references introduced by Claw that no other current owner holds, add --remove-unused to both preview and apply. To target specific referenced resources instead, use --remove-referenced repeatedly:

openclaw claws remove incident-triage \
  --dry-run \
  --remove-referenced 'plugin:@acme/audit-plugin@2.0.0'

Only use --force-referenced after you have reviewed the listed dependents, independent owners, and existing origin. It permits selected cleanup even when those conflicts are present; it does not bypass plan-integrity approval.

Export an installed agent

Export creates a new package directory and fails if the destination already exists or managed state has drifted:

openclaw claws export incident-triage --out ./incident-triage-export --json

The output includes package.json, canonical CLAW.md, and managed workspace sidecars. This is a portable Claw package, not a full-instance backup: unrelated agents, credentials, sessions, and unowned local state are not included.

Command reference

For experimental machine-readable output, use --json.

See also

• Agents
• Skills
• Plugins
• Cron jobs
• MCP configuration