{"_id":"@cogineai/clawpacker","_rev":"4-ac281a8c97edcd1f5a4630beb353adec","name":"@cogineai/clawpacker","dist-tags":{"latest":"0.4.0"},"versions":{"0.1.0":{"name":"@cogineai/clawpacker","version":"0.1.0","license":"MIT","_id":"@cogineai/clawpacker@0.1.0","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/clawpack","bugs":{"url":"https://github.com/cogine-ai/clawpack/issues"},"bin":{"clawpacker":"dist/cli.js"},"dist":{"shasum":"9ed698ab5ed731fd79a5c21911edaacebf1ab208","tarball":"https://registry.npmjs.org/@cogineai/clawpacker/-/clawpacker-0.1.0.tgz","fileCount":60,"integrity":"sha512-yweicq4flXrBs3GpnI+o7kpA2gqhNX3jBjOZmJfHe873hvv63OTOWBScayw/mwSTGJ0cSQhLxTd0oXtn9QfQ6Q==","signatures":[{"sig":"MEUCIED/+XitscecdJgaj/6YZ6HUdNRWiaRCEHS+h0l+8WimAiEAgzrUtoSntzK4PUuemmbotVmyuxniCDGPdt9xDIS9jOY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":99961},"engines":{"node":">=20"},"gitHead":"424a02093fbaefd25b821690bace4d09abe82288","scripts":{"dev":"tsx src/cli.ts","test":"node --test","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/clawpack.git","type":"git"},"_npmVersion":"11.9.0","description":"Portable OpenClaw agent/workspace template CLI for inspect/export/import/validate workflows.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"commander":"^13.1.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","typescript":"^5.8.2","@types/node":"^22.13.10"},"_npmOperationalInternal":{"tmp":"tmp/clawpacker_0.1.0_1773677441670_0.6474459462387621","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cogineai/clawpacker","version":"0.2.0","license":"MIT","_id":"@cogineai/clawpacker@0.2.0","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/clawpack","bugs":{"url":"https://github.com/cogine-ai/clawpack/issues"},"bin":{"clawpacker":"dist/cli.js"},"dist":{"shasum":"1354af0831eaf418889f1d2f850e61d2c7547626","tarball":"https://registry.npmjs.org/@cogineai/clawpacker/-/clawpacker-0.2.0.tgz","fileCount":72,"integrity":"sha512-fpjYRc2wR58CH33sOWve9Z4VdPNNkz+ulPn1a+WDARqRbGIGICQi+l7Ywn52MrWp+ep2Cdr+RKaoA1kM98pcFg==","signatures":[{"sig":"MEUCIEdKpwedC5dbBYt/ULEjaPu/AYXl7dLzW2ptuumE+yT4AiEAkmjiCZAnMXo7bo1EulybLqqfknWAR2YXkjQUn2TG3hY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":147266},"engines":{"node":">=20"},"gitHead":"cf7dcbd1362193a96f34ebe0efb1767445d67667","scripts":{"dev":"tsx src/cli.ts","lint":"biome check .","test":"tsx --test tests/*.test.ts","build":"tsc -p tsconfig.json","lint:fix":"biome check --write .","test:coverage":"c8 --reporter=text --reporter=lcov tsx --test tests/*.test.ts","prepublishOnly":"npm run build && npm test","test:coverage:check":"c8 --check-coverage --lines 70 --branches 60 --functions 70 tsx --test tests/*.test.ts"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/clawpack.git","type":"git"},"_npmVersion":"11.9.0","description":"Portable OpenClaw agent/workspace template CLI for inspect/export/import/validate workflows.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"tar":"^7.5.11","commander":"^13.1.0","strip-json-comments":"^5.0.3"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^11.0.0","tsx":"^4.19.3","typescript":"^5.8.2","@types/node":"^22.13.10","@biomejs/biome":"^2.4.7"},"_npmOperationalInternal":{"tmp":"tmp/clawpacker_0.2.0_1773868901938_0.09192026576371815","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@cogineai/clawpacker","version":"0.3.0","license":"MIT","_id":"@cogineai/clawpacker@0.3.0","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"homepage":"https://github.com/cogine-ai/clawpack","bugs":{"url":"https://github.com/cogine-ai/clawpack/issues"},"bin":{"clawpacker":"dist/cli.js"},"dist":{"shasum":"0b6a739292cebadd46776a9e701d6c6bac803e83","tarball":"https://registry.npmjs.org/@cogineai/clawpacker/-/clawpacker-0.3.0.tgz","fileCount":87,"integrity":"sha512-MlClh1445CXwUu2rS5QfKK1KRQBuGtqt+Pq21VsH8BrI1gVXPC8HixudIhvqYe06/ZHFqRTZzqCKaPO/HyoJEw==","signatures":[{"sig":"MEYCIQCPiP+Ooi86MRxHO/gj/h4mK256N7F02DMa/e2onx+rIAIhAItM4q1nklmlH3jhEtkmuPdyXyITCSmKV23T86OPSXJJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":238410},"engines":{"node":">=20"},"gitHead":"4ca0d59ada2206dfa3158c4efb941624ed52c7c8","scripts":{"dev":"tsx src/cli.ts","lint":"biome check .","test":"tsx --test tests/*.test.ts","build":"tsc -p tsconfig.json","lint:fix":"biome check --write .","test:coverage":"c8 --reporter=text --reporter=lcov tsx --test tests/*.test.ts","prepublishOnly":"npm run build && npm test","test:coverage:check":"c8 --check-coverage --lines 70 --branches 60 --functions 70 tsx --test tests/*.test.ts"},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"repository":{"url":"git+https://github.com/cogine-ai/clawpack.git","type":"git"},"_npmVersion":"11.9.0","description":"Portable OpenClaw agent/workspace template CLI for inspect/export/import/validate workflows.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"tar":"^7.5.11","commander":"^13.1.0","strip-json-comments":"^5.0.3"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^11.0.0","tsx":"^4.19.3","typescript":"^5.8.2","@types/node":"^22.13.10","@biomejs/biome":"^2.4.7"},"_npmOperationalInternal":{"tmp":"tmp/clawpacker_0.3.0_1774165271484_0.6478368287499261","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@cogineai/clawpacker","version":"0.4.0","description":"Portable OpenClaw agent/workspace template CLI for inspect/export/import/validate workflows.","bin":{"clawpacker":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.json","dev":"tsx src/cli.ts","lint":"biome check .","lint:fix":"biome check --write .","prepublishOnly":"npm run build && npm test","test":"tsx --test tests/*.test.ts","test:coverage":"c8 --reporter=text --reporter=lcov tsx --test tests/*.test.ts","test:coverage:check":"c8 --check-coverage --lines 70 --branches 60 --functions 70 tsx --test tests/*.test.ts"},"engines":{"node":">=20"},"dependencies":{"commander":"^13.1.0","json5":"^2.2.3","tar":"^7.5.11"},"devDependencies":{"@biomejs/biome":"^2.4.7","@types/node":"^22.13.10","c8":"^11.0.0","tsx":"^4.19.3","typescript":"^5.8.2"},"repository":{"type":"git","url":"git+https://github.com/cogine-ai/clawpack.git"},"homepage":"https://github.com/cogine-ai/clawpack","bugs":{"url":"https://github.com/cogine-ai/clawpack/issues"},"license":"MIT","gitHead":"3e7dca3373681f236fb8714b9bd7b28857f88621","_id":"@cogineai/clawpacker@0.4.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-2gaFApiyWrj3v1hhyOzO2D6yUSf57PiG/ovnvb4Ap61T/QMc5pWQ5yIekFfWMpvHFMrLA1OnifXseQb5Z2fPRw==","shasum":"21d1ec78a8e5c654877c85dc5ab3ad83247632ac","tarball":"https://registry.npmjs.org/@cogineai/clawpacker/-/clawpacker-0.4.0.tgz","fileCount":90,"unpackedSize":347821,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGUtKzJ7KsfgdXL6F0yprcTn0xO0Y6ty79oWPz9+/Z1kAiAs4QJm69nxWWD4yg+JJpb/Yg/Iz4QDOeM7mH5XBh/CZA=="}]},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"directories":{},"maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clawpacker_0.4.0_1776520345841_0.9109890221996051"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T16:10:41.501Z","modified":"2026-04-18T13:52:26.110Z","0.1.0":"2026-03-16T16:10:41.832Z","0.2.0":"2026-03-18T21:21:42.097Z","0.3.0":"2026-03-22T07:41:11.633Z","0.4.0":"2026-04-18T13:52:25.988Z"},"bugs":{"url":"https://github.com/cogine-ai/clawpack/issues"},"license":"MIT","homepage":"https://github.com/cogine-ai/clawpack","repository":{"type":"git","url":"git+https://github.com/cogine-ai/clawpack.git"},"description":"Portable OpenClaw agent/workspace template CLI for inspect/export/import/validate workflows.","maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"readme":"# Clawpacker\n\n> Portable OpenClaw agent/workspace templates for sharing, cloning, and rehydrating on another instance.\n\nClawpacker is a small TypeScript CLI for exporting the portable parts of an OpenClaw agent workspace into a declarative package, then importing that package into another OpenClaw setup.\n\n## Why this exists\n\nOpenClaw agents often live inside a workspace with persona files, conventions, and a bit of agent config glue. Recreating that setup by hand is annoying, error-prone, and easy to drift.\n\nClawpacker focuses on the reusable part of that problem:\n\n- capture the workspace files that define an agent's behavior\n- extract a portable slice of agent config\n- restore that template somewhere else\n- clearly tell you what still needs manual setup\n\nThis is **template portability**, not full-instance backup.\n\n## Status\n\n**Internal alpha.** The current CLI is usable for early experiments (package format v2), but the format and UX should still be treated as early-stage.\n\nUse it when you want to:\n\n- package an existing OpenClaw workspace as a reusable template\n- move a persona/operator setup between instances with minimal manual work\n- validate what was imported\n\nDo **not** treat it as a production-grade backup, archival, or disaster-recovery tool yet.\n\n## What Clawpacker does\n\n### Included\n\nClawpacker uses a **blacklist model** — it includes all files in the workspace (including subdirectories) except those matching explicit exclusion rules.\n\nThe following top-level files are recognized by current OpenClaw docs as **bootstrap files** and are flagged in the manifest when present:\n\n`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `MEMORY.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`\n\n`BOOT.md` is also a documented workspace file, but it is **not** treated as a bootstrap file. If present, clawpacker includes it as a normal workspace file.\n\nFor validation purposes, clawpacker only requires the core workspace contract:\n\n`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`\n\nThe following OpenClaw workspace files are treated as **optional** and their absence does not make a workspace invalid:\n\n`BOOT.md`, `BOOTSTRAP.md`, `HEARTBEAT.md`, `MEMORY.md`, `memory.md`, `memory/*.md`\n\nAll other workspace files are included as well, preserving directory structure.\n\nThe package also contains metadata:\n\n- `manifest.json`\n- `config/agent.json`\n- `config/import-hints.json`\n- `config/skills-manifest.json`\n- `meta/checksums.json`\n- `meta/export-report.json`\n\n### Excluded\n\nClawpacker excludes the following subdirectories if they appear inside the workspace:\n\n- `.git`\n- `.openclaw`\n- `node_modules`\n\nAnd these file patterns:\n\n- `memory/*.md` daily logs\n\nThe `memory/*.md` exclusion is a **clawpacker product policy**, not an OpenClaw workspace requirement. It exists to keep exports conservative and portable by default.\n\nThese rules only apply to contents **within** the scanned workspace directory. The parent `~/.openclaw/` installation and its config files are not part of the workspace scan — OpenClaw config is read separately via `--config` or config discovery.\n\nBeyond file-level exclusions, Clawpacker never exports or restores:\n\n- secrets, auth state, cookies, API keys, credentials\n- session/runtime state\n- live routing bindings / routing state\n- live cron scheduling / scheduled-job registration\n- globally installed skills or extensions\n- machine-specific absolute-path behavior that is not portable\n\n### Skills model\n\nClawpacker records a **skills topology snapshot**.\n\nThat snapshot is source-backed:\n\n- visible skill roots and their precedence\n- the effective per-agent skill allowlist, when configured\n- `skills.entries.*` settings such as explicit enable/disable and env/API-key wiring\n- whether a visible skill state is `portable`, `host-bound`, `reinstall-required`, or `unsupported`\n\nClawpacker still does **not** auto-install skills for you. Workspace-owned skill implementations can travel with the exported workspace; managed/shared/bundled/plugin-provided skills remain host-managed and require manual reinstall or reconfiguration on the target instance.\n\n### Runtime layer (optional)\n\nIn addition to workspace files, OpenClaw agents often have runtime configuration stored in a separate **agentDir**. Clawpacker can optionally package a narrow, labeled slice of this runtime layer alongside the workspace.\n\nThis is an **optional portability convenience**, not a full backup of the agent runtime directory.\n\n#### Runtime compatibility labels\n\nClawpacker classifies detected runtime files and follow-up work with four compatibility labels:\n\n| Label | Meaning | Current examples |\n|-------|---------|------------------|\n| `official` | Source-backed and aligned with the current runtime contract | `models.json` |\n| `inferred` | Useful convenience files, but not a strong current OpenClaw portability contract | `settings.json`, `prompts/**`, `themes/**` |\n| `manual` | Requires explicit operator follow-up | reinstalling skills, reconfiguring bindings, reviewing inferred files |\n| `unsupported` | Not currently treated as canonical portable per-agent artifacts | `skills/**`, `extensions/**` |\n\n`inspect`, `export`, package metadata, and `validate` all surface these same labels so the tool makes a clean distinction between what is source-backed, what is inferred, what is unsupported, and what still needs operator action.\n\n#### The three modes\n\n| Mode | What gets packaged | When to use |\n|------|-------------------|-------------|\n| `none` | Nothing from agentDir | You only need workspace files |\n| `default` | Only `official` runtime artifacts | Honest default for portability checks and packaging |\n| `full` | `official` plus `inferred` runtime artifacts | When you intentionally want extra convenience files and understand they are not an official capability contract |\n\nUse `--runtime-mode <mode>` on `inspect` and `export`. When omitted, `inspect` defaults to `default`; `export` skips the runtime layer unless the flag is explicitly provided.\n\n`full` does **not** include `skills/**` or `extensions/**`. Those are reported as `unsupported`, not packaged.\n\n#### What is always excluded\n\nRegardless of mode, Clawpacker never packages these from agentDir:\n\n- `auth.json`, `auth-profiles.json` — authentication state\n- `sessions/**` — session data\n- `.git/**`, `node_modules/**`, `npm/**`, `bin/**` — toolchain artifacts\n- `tools/**`, `caches/**`, `logs/**` — ephemeral runtime state\n- Files with extensions `.log`, `.lock`, `.tmp`, `.bak`, `.swp`, `.pid`\n\nThese exclusions exist because auth and session state is inherently non-portable and should be established fresh on the target instance.\n\n#### models.json sanitization\n\nWhen `models.json` is included, Clawpacker **sanitizes** it before packaging:\n\n- API keys, secrets, and `$secretRef` objects are stripped\n- Secret-bearing HTTP headers are removed\n- Non-sensitive fields (model id, provider, max tokens, temperature) are preserved\n\nIf sanitization removes everything useful, the file is excluded entirely and a warning is emitted.\n\n#### settings.json path analysis\n\n`settings.json` is an `inferred` artifact, so this analysis runs only when `settings.json` is actually included, for example with `--runtime-mode full`.\n\nClawpacker analyzes path-like values in `settings.json` and classifies them:\n\n| Classification | Meaning | On import |\n|---------------|---------|-----------|\n| `package-internal-workspace` | Points inside the source workspace | Rewritten to target workspace path |\n| `package-internal-agentDir` | Points inside the source agentDir | Rewritten to target agentDir path |\n| `relative` | Relative path (e.g. `./data`) | Preserved as-is |\n| `external-absolute` | Absolute path outside workspace/agentDir | Preserved (may need manual update) |\n| `host-bound` | Platform-specific path (e.g. `C:\\...`, `/proc/...`) | Preserved (warning emitted) |\n\n#### Runtime import behavior\n\nWhen importing a package that includes a runtime layer:\n\n- **`--target-agent-dir`** specifies where runtime files should be written. If omitted, Clawpacker attempts to resolve it from the target OpenClaw config.\n- If no target agentDir can be resolved, import **blocks** and tells you what is needed.\n- If runtime files already exist at the target agentDir, import **blocks** unless `--force` is passed. Only allowlisted runtime files are overwritten — auth and session files are never written.\n- If a target OpenClaw config is provided, the agent entry is upserted with the agentDir path.\n- `settings.json` paths referencing the source workspace or agentDir are automatically rewritten to the target paths when `settings.json` is present in the package.\n\nUse `--dry-run` to preview the full import plan (including runtime file list, path rewrites, and collision detection) before committing.\n\n#### agentDir resolution\n\nThe agentDir is resolved from the OpenClaw config by matching the agent entry that owns the source workspace. This requires:\n\n1. A readable OpenClaw config (via `--config`, `OPENCLAW_CONFIG_PATH`, or `~/.openclaw/openclaw.json`)\n2. An agent entry with an `agentDir` field\n\nIf the config is missing or the agent entry has no `agentDir`, the runtime layer is skipped on inspect, and export errors out with a clear message.\n\n## Install\n\n### Published package\n\n```bash\nnpm install -g @cogineai/clawpacker\nclawpacker --help\n```\n\n### From source\n\n```bash\nnpm install\nnpm run build\n```\n\nRun the built CLI:\n\n```bash\nnode dist/cli.js --help\n```\n\n### Node requirement\n\n- Node.js `>= 20`\n\n## Command overview\n\nAfter building, the CLI exposes four commands:\n\n- `inspect` — analyze a workspace before packaging\n- `export` — write a `.ocpkg/` directory or `.ocpkg.tar.gz` archive\n- `import` — restore a package into a target workspace\n- `validate` — verify an imported workspace target\n\nIf you install the published package, the CLI command is:\n\n```bash\nclawpacker\n```\n\nFor local source usage, you can still run:\n\n```bash\nnode dist/cli.js\n```\n\n## Usage\n\n### 1) Inspect a source workspace\n\nHuman-readable report:\n\n```bash\nnode dist/cli.js inspect \\\n  --workspace ./tests/fixtures/source-workspace\n```\n\nWith runtime layer inspection:\n\n```bash\nnode dist/cli.js inspect \\\n  --workspace ./tests/fixtures/source-workspace \\\n  --config ./tests/fixtures/openclaw-config/source-config.jsonc \\\n  --runtime-mode default\n```\n\nMachine-readable JSON report:\n\n```bash\nnode dist/cli.js inspect \\\n  --workspace ./tests/fixtures/source-workspace \\\n  --config ./tests/fixtures/openclaw-config/source-config.jsonc \\\n  --runtime-mode default \\\n  --json\n```\n\nWhat `inspect` tells you:\n\n- which workspace files are included\n- which files are excluded or ignored\n- whether a portable agent definition could be derived\n- which fields are portable vs import-time inputs\n- which skills were detected\n- compatibility labels grouped as `official`, `inferred`, `manual`, and `unsupported` (when `--runtime-mode` is `default` or `full`)\n- warnings you should expect on export/import\n\n### 2) Export a package\n\nDirectory package (workspace only):\n\n```bash\nnode dist/cli.js export \\\n  --workspace ./tests/fixtures/source-workspace \\\n  --out ./tests/tmp/example-supercoder.ocpkg \\\n  --name supercoder-template \\\n  --runtime-mode none\n```\n\nDirectory package with runtime layer:\n\n```bash\nnode dist/cli.js export \\\n  --workspace ./tests/fixtures/source-workspace \\\n  --config ./tests/fixtures/openclaw-config/source-config.jsonc \\\n  --out ./tests/tmp/example-supercoder.ocpkg \\\n  --name supercoder-template \\\n  --runtime-mode default\n```\n\nSingle-file archive:\n\n```bash\nnode dist/cli.js export \\\n  --workspace ./tests/fixtures/source-workspace \\\n  --config ./tests/fixtures/openclaw-config/source-config.jsonc \\\n  --out ./tests/tmp/example-supercoder.ocpkg \\\n  --name supercoder-template \\\n  --runtime-mode default \\\n  --archive\n```\n\nThe `--archive` flag produces a `.ocpkg.tar.gz` file for easier transport.\n\nOutput defaults to human-readable text. Add `--json` for machine-readable output:\n\n```json\n{\n  \"status\": \"ok\",\n  \"packageRoot\": \".../example-supercoder.ocpkg\",\n  \"manifestPath\": \".../example-supercoder.ocpkg/manifest.json\",\n  \"fileCount\": 12,\n  \"skills\": {\n    \"mode\": \"topology-snapshot\"\n  },\n  \"runtimeMode\": \"default\",\n  \"runtimeFiles\": [\"models.json\"],\n  \"runtimeOfficialFiles\": [\"models.json\"],\n  \"runtimeGroundedFiles\": [\"models.json\"],\n  \"runtimeInferredFiles\": [\"settings.json\", \"prompts/system.md\"],\n  \"runtimeUnsupportedFiles\": [\"skills/review/SKILL.md\"],\n  \"compatibility\": [\n    {\n      \"label\": \"official\",\n      \"message\": \"Source-backed runtime artifacts\",\n      \"items\": [\"models.json\"]\n    },\n    {\n      \"label\": \"manual\",\n      \"message\": \"Skills are manifest-only and may require manual installation.\"\n    }\n  ]\n}\n```\n\nFor directory exports, `manifestPath` points to the generated `manifest.json` inside the package directory.\nFor archive exports, `manifestPath` is set to the archive file path itself so JSON output never points at a deleted staging path.\n\n### 3) Import a package\n\nAccepts both `.ocpkg/` directories and `.ocpkg.tar.gz` archives:\n\n```bash\nnode dist/cli.js import \\\n  ./tests/tmp/example-supercoder.ocpkg \\\n  --target-workspace ./tests/tmp/workspace-supercoder-imported \\\n  --agent-id supercoder-imported \\\n  --config ./tests/tmp/target-openclaw-config.json\n```\n\nImport with runtime layer targeting a specific agentDir:\n\n```bash\nnode dist/cli.js import \\\n  ./tests/tmp/example-supercoder.ocpkg \\\n  --target-workspace ./tests/tmp/workspace-supercoder-imported \\\n  --agent-id supercoder-imported \\\n  --target-agent-dir ~/.openclaw/agents/supercoder-imported \\\n  --config ./tests/tmp/target-openclaw-config.json\n```\n\nPreview the import plan without writing anything:\n\n```bash\nnode dist/cli.js import \\\n  ./tests/tmp/example-supercoder.ocpkg \\\n  --target-workspace ./tests/tmp/workspace-supercoder-imported \\\n  --agent-id supercoder-imported \\\n  --dry-run\n```\n\nNotes:\n\n- `--target-workspace` is required\n- `--agent-id` is strongly recommended and becomes required in practice for collision-safe import planning\n- `--target-agent-dir` is required when the package includes a runtime layer and no agentDir is discoverable from the target config\n- `--dry-run` prints the import plan (including runtime details, path rewrites, and collision info) and exits without writing files\n- if the target workspace or target agent already exists, import blocks unless you pass `--force`\n- if runtime files already exist at the target agentDir, import blocks unless `--force` is passed; auth and session files are never written even with `--force`\n- if no config is found, import can still restore workspace files, but config registration and runtime import become limited\n\n### 4) Validate the imported result\n\n```bash\nnode dist/cli.js validate \\\n  --target-workspace ./tests/tmp/workspace-supercoder-imported \\\n  --agent-id supercoder-imported \\\n  --config ./tests/tmp/target-openclaw-config.json\n```\n\nWhen a runtime layer was imported, validate also checks runtime file integrity:\n\n```bash\nnode dist/cli.js validate \\\n  --target-workspace ./tests/tmp/workspace-supercoder-imported \\\n  --agent-id supercoder-imported \\\n  --target-agent-dir ~/.openclaw/agents/supercoder-imported \\\n  --config ./tests/tmp/target-openclaw-config.json\n```\n\nThe `--target-agent-dir` flag can be omitted — validate auto-infers it from import metadata when available.\n\nOutput defaults to human-readable text. Add `--json` for a structured report with:\n\n- `passed` — checks that succeeded (including runtime file presence and agentDir consistency)\n- `warnings` — non-blocking observations (e.g. auth files found at agentDir)\n- `failed` — checks that failed (e.g. missing runtime files, agentDir mismatch)\n- `nextSteps` — recommended actions\n\n## OpenClaw config awareness\n\nClawpacker is OpenClaw-aware, but intentionally narrow.\n\nWhen you provide `--config`, or when import can discover a nearby OpenClaw config, Clawpacker can:\n\n- derive a portable agent definition from an existing config entry\n- classify config fields as portable, excluded, or requiring import-time input\n- upsert the imported agent into the target OpenClaw config\n- validate that the imported workspace path matches the target config entry\n\n### Config discovery behavior\n\nConfig is resolved in this order:\n\n1. explicit `--config` flag\n2. `OPENCLAW_CONFIG_PATH` environment variable\n3. a nearby config discovered from `cwd` by checking `./.openclaw/openclaw.json`, `./openclaw.json`, and then the same two locations in up to four parent directories\n4. `~/.openclaw/openclaw.json` (default)\n\nNotes:\n- if you pass `--config`, Clawpacker does **not** fall through to env / nearby / default discovery when that path is missing\n- relative `workspace` and `agentDir` values inside config are resolved relative to the config file directory\n- workspace matching prefers exact resolved paths; basename-only fallback is used only when it is unambiguous\n\n### Portable config philosophy\n\nClawpacker does **not** export raw OpenClaw config wholesale.\n\nInstead, it extracts a portable slice of agent config, including:\n\n- agent id and display name\n- workspace basename suggestion\n- identity name\n- default model, when present\n- tools, skills, heartbeat, sandbox, and runtime settings\n\nAnd it explicitly excludes things like:\n\n- live routing bindings as portable config\n- secrets\n- provider/account-specific runtime state\n\n## Safety model\n\nClawpacker is designed to be conservative.\n\n### Export safety\n\n- all workspace files are included except explicitly excluded directories and patterns\n- daily memory logs (`memory/*.md`) are excluded by default as a clawpacker portability policy\n- package contents are declared in a manifest instead of hidden in opaque state\n- checksums are generated for integrity verification\n- runtime layer is opt-in via `--runtime-mode`\n- `models.json` is sanitized before packaging — API keys, secrets, and `$secretRef` objects are removed\n- auth and session files are never included in the runtime layer regardless of mode\n\n### Import safety\n\n- import is planned before it executes\n- existing workspace collisions block by default\n- existing config agent collisions block by default\n- existing runtime file collisions block by default\n- `--force` is required to overwrite existing targets (workspace and runtime files); workspace files are replaced in-place without removing unrelated files\n- `--force` never writes auth or session files — these are always excluded\n- `settings.json` paths referencing the source workspace or agentDir are automatically rewritten to the target paths\n- import writes local metadata so validation can confirm what happened later\n\n### Post-import safety expectations\n\nEven after a successful import, you should still:\n\n- review `USER.md` and `TOOLS.md`, plus `MEMORY.md` if present\n- reinstall any required skills manually\n- review imported binding hints metadata at `.openclaw-agent-package/binding-hints.json` after import, or `meta/binding-hints.json` in the source package before import, then reconfigure routing bindings and any scheduled jobs manually\n- run `openclaw doctor`\n- verify model/provider availability on the target instance\n\nToday, clawpacker does not package or restore live OpenClaw top-level `bindings[]` entries or scheduled jobs. There is no `config/cron.json` portability contract in the package format. When source config is available, export may include matching routing entries as source-backed hints in `meta/binding-hints.json`, and import preserves those hints in `.openclaw-agent-package/binding-hints.json`; they remain metadata only and must be reapplied manually on the target instance.\n\nClawpacker packages a portable workspace template plus an optional runtime slice. For full-instance moves or environment repair, follow the official OpenClaw migration flow rather than treating clawpacker as a complete instance backup.\n\n## Package structure\n\nA typical package looks like this:\n\n```text\nsupercoder-template.ocpkg/\n  manifest.json\n  workspace/\n    AGENTS.md\n    SOUL.md\n    IDENTITY.md\n    USER.md\n    TOOLS.md\n    MEMORY.md\n    HEARTBEAT.md\n    custom-prompts/\n      review.md\n    ...                     # any other workspace files\n  config/\n    agent.json\n    import-hints.json\n    skills-manifest.json\n  meta/\n    binding-hints.json      # optional source-backed routing hints; metadata only\n    checksums.json\n    export-report.json\n  runtime/                  # present when --runtime-mode is default or full\n    manifest.json\n    checksums.json\n    path-rewrites.json\n    settings-analysis.json  # present when inferred settings.json was included\n    files/\n      models.json           # sanitized — no API keys or secrets\n      settings.json         # present only when inferred files are included\n      prompts/              # present only when inferred files are included\n        system.md\n      themes/               # present only when inferred files are included\n        dark.json\n```\n\nThe `workspace/` directory mirrors the source workspace structure. All non-excluded files are included, so the contents vary depending on what lives in the source workspace.\n\nThe `runtime/` subtree is only present when `--runtime-mode default` or `--runtime-mode full` is used on export. Its `manifest.json` records the mode, source agentDir, compatibility labels, and which files were included or excluded. The `files/` subdirectory contains only the runtime files that the selected mode is allowed to package.\n\nPackages can also be distributed as single-file `.ocpkg.tar.gz` archives.\n\n## What is intentionally out of scope\n\n- full OpenClaw instance backup (the runtime layer is a portable slice, not a full agentDir copy)\n- secret migration (API keys and auth tokens are stripped on export)\n- auth/session migration (auth files are always excluded)\n- automatic routing binding restore\n- raw cron export/import or scheduler registration\n- zero-touch import across mismatched environments\n\n## Roadmap / known limitations\n\nNear-term likely improvements:\n\n- richer import guidance when models or inferred runtime files are missing\n- better package compatibility/version negotiation\n\nCurrent limitations to be aware of:\n\n- package format should still be treated as early-stage (currently v2)\n- the exported skills snapshot is descriptive, not an auto-installer; host-managed, bundled, extra-dir, and plugin-provided skills still require manual reinstall/reconfiguration\n- runtime `skills/**` and `extensions/**` are still classified as unsupported runtime artifacts and are not bundled\n- `--force` uses file-level replacement semantics — only files present in the package are overwritten; unrelated files in the target workspace are preserved\n- OpenClaw config support is minimal by design\n- runtime layer path rewriting only handles inferred `settings.json` — other config files with embedded paths require manual update\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nBuild:\n\n```bash\nnpm run build\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\nRun the CLI directly in dev:\n\n```bash\nnpm run dev -- --help\n```\n\n## Verifying the examples locally\n\nA practical smoke path is:\n\n```bash\nnpm run build\nnode dist/cli.js inspect --workspace ./tests/fixtures/source-workspace --json\nnode dist/cli.js export --workspace ./tests/fixtures/source-workspace --out ./tests/tmp/readme-demo.ocpkg --runtime-mode none\nnode dist/cli.js import ./tests/tmp/readme-demo.ocpkg --target-workspace ./tests/tmp/readme-demo-target --agent-id readme-demo\nnode dist/cli.js validate --target-workspace ./tests/tmp/readme-demo-target --agent-id readme-demo\nnpm test\n```\n\n## Naming\n\nThe npm package name is **`@cogineai/clawpacker`** while the GitHub repository remains **`cogine-ai/clawpack`**.\n\nWhy this naming split:\n\n- short and memorable\n- feels native to the OpenClaw ecosystem\n- communicates portability/transport clearly\n- keeps the repository path stable while making the published package name explicit\n\n---\n\nIf you are evaluating this repo for internal alpha use: treat it as a practical portability prototype with a conservative safety model, not as a finished backup product.\n","readmeFilename":"README.md"}