> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Claws # `openclaw claws` A Claw is a versioned setup for one new OpenClaw agent. It can describe the agent configuration, workspace files, skills, plugins, MCP servers, and cron jobs that agent needs. A Claw does not replace or modify an existing agent. Claws are experimental. Their schema, command output, and lifecycle may change. Enable the command surface explicitly: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_EXPERIMENTAL_CLAWS=1 ``` The current CLI reads a local package directory 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. ## Create a grouped manifest Start with a version 1 JSON manifest: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "schemaVersion": 1, "agent": { "id": "incident-triage", "name": "Incident triage", "tools": { "deny": ["exec"] } }, "workspace": { "bootstrapFiles": {} }, "packages": [], "mcpServers": {}, "cronJobs": [] } ``` 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. Workspace files are declared by path and read from package sidecars. Bootstrap files such as `SOUL.md` use named entries; additional files use package-relative sources and workspace-relative targets: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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. ## Inspect and preview Validate the source without planning local changes: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw claws inspect ./incident-triage.claw.json ``` Preview all proposed lifecycle actions: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw claws add ./incident-triage.claw.json \ --yes \ --plan-integrity ``` `--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. Adding a Claw creates the new agent and workspace configuration, writes declared workspace files, installs or reuses declared skill and plugin artifacts, and records provenance. Existing files are not overwritten, and retries fail closed when owned content drifted. Later Claws stages add other declared resources. ## Inspect installed state ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw claws status openclaw claws status incident-triage --json ``` `status` compares the installed agent and its recorded workspace and package provenance with current state. It reports incomplete installs, missing resources, and drift without changing local state. 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. ## Remove an installed Claw Preview removal before selecting cleanup: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw claws remove incident-triage --dry-run --json openclaw claws remove incident-triage \ --yes \ --plan-integrity ``` The default removes eligible managed state and releases referenced state. Modified files and resources with another current owner are retained or blocked. Cleanup choices are part of the plan digest; `--yes` never broadens them. Globally installed plugins are retained while this Claw's reference is released; use the ordinary plugin lifecycle separately when you intend to uninstall a process-wide plugin. To remove unchanged Claw-introduced references that have no other current owner, include `--remove-unused` in both preview and apply. To select exact referenced resources instead, repeat `--remove-referenced`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw claws remove incident-triage \ --dry-run \ --remove-referenced 'plugin:@acme/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. ## Command reference | Command | Purpose | | ------------------------------ | --------------------------------------------------- | | `claws inspect ` | Validate a package directory or JSON manifest. | | `claws add ` | Preview or create one new agent and workspace. | | `claws status [claw-or-agent]` | Report installed state, ownership, and drift. | | `claws remove ` | Preview or remove the agent and eligible resources. | Use `--json` for experimental machine-readable output. ## See also * [Agents](/cli/agents) * [Skills](/tools/skills) * [Plugins](/tools/plugin)