# ocm
**Install, run, update, and manage OpenClaw — properly.**
OCM gives OpenClaw one coherent workflow across stable releases, local checkouts, supervised env gateways, upgrades, snapshots, and ongoing maintenance.
OpenClaw is easy to start once. It gets messier when you want more than one setup, need stable and local development side by side, or want confidence about what is actually running. `ocm` fixes that.
Once an environment exists, `ocm` can be your normal OpenClaw entrypoint:
```bash
ocm @mira -- tui
ocm @mira -- status
ocm @mira -- onboard
```
## What ocm manages
`ocm` keeps the moving parts separate:
- **envs** — isolated OpenClaw environments
- **runtimes** — installed and pinned OpenClaw releases
- **launchers** — named command recipes for local-dev or custom runs
- **services** — background OpenClaw processes tied to one environment
That split is what makes stable releases, local development, upgrades, and service management fit together cleanly.
## Why people use it
Use `ocm` when you want:
- one clean OpenClaw environment per project, task, or instance
- one command path for OpenClaw itself through `ocm @<env> -- <command>`
- published OpenClaw releases installed locally and updated safely
- local checkout workflows that feel just as normal as released builds
- one OCM background service that can supervise env gateways cleanly
- snapshots, export/import, and safer cleanup
## Install
Install the npm distribution, available starting with OCM v0.2.40:
```bash
npm install --global @openclaw/ocm
```
See [npm installation and updates](npm/README.md) for Node requirements,
project-local installs, npx, and daemon refresh behavior.
Install with Homebrew on macOS (Apple Silicon or Intel) or Linux x86_64:
```bash
brew install openclaw/tap/ocm
```
Upgrade Homebrew installations with `brew upgrade openclaw/tap/ocm`, not
`ocm self update`. Since v0.2.40, OCM refuses to overwrite a
Homebrew-managed executable. `ocm self update --check` remains available.
Install the latest release:
```bash
curl -fsSL https://github.com/openclaw/ocm/releases/latest/download/install.sh | bash
```
Install a specific release:
```bash
curl -fsSL https://github.com/openclaw/ocm/releases/download/v<ocm-version>/install.sh | bash -s -- --version v<ocm-version>
```
Update an installer-managed install:
```bash
ocm self update
ocm self update --check
```
Install from source:
```bash
cargo install --locked --path .
```
Source installs require Rust 1.88 or newer. Release installers verify the selected archive against the published `SHA256SUMS` before extraction.
Inside this repo, use the development wrapper:
```bash
./bin/ocm help
```
Published OpenClaw release flows prefer host Node.js and npm when Node satisfies the selected package's `engines.node` requirement.
OCM checks the verified package before installation and the installed manifest before ordinary execution.
On supported platforms, OCM can manage a private Node.js 24.22.1 copy when the host tools are missing or incompatible.
OCM reuses only the selected private Node.js version after checking the executable. Older private caches must be refreshed with `ocm start` or `ocm runtime install --channel stable` before offline launches.
Packages without `engines.node` retain the legacy baseline of Node.js `22.22.3+`, `24.15.0+`, or `25.9.0+`.
`ocm doctor host` reports baseline tool availability and private-toolchain support, not compatibility with a particular release; package compatibility is checked when installing or running it.
Interactive release setup can also offer to install `git` for repo-aware coding workflows when it is missing.
Local checkout flows keep using whatever command and toolchain you choose.
## Start quickly
If you want the guided path:
```bash
ocm setup
```
If you already know what you want:
```bash
ocm start
```
`setup` walks you through the choices. `start` creates or reuses an environment, installs the latest stable OpenClaw release by default, writes the minimum local config needed to boot, and keeps it running in the background. Use `--onboard` when you want the interactive OpenClaw setup flow instead: onboarding runs before OCM installs and starts the service. If onboarding fails or is cancelled, OCM leaves a new environment stopped; retry with `ocm start <name> --onboard`. If you do not pass a name, `ocm` generates one for you.
If you are developing OpenClaw itself, use the dev path:
```bash
ocm dev shaks
ocm dev shaks --root /tmp/shaks
ocm dev shaks --no-ui
ocm dev shaks --no-watch
ocm dev shaks --no-watch --no-ui
ocm dev shaks --force
ocm dev stop shaks
ocm dev shaks --repo /path/to/openclaw --watch --force
ocm dev shaks --service
ocm dev shaks --onboard
```
`dev` creates or reuses an isolated env, uses the selected OpenClaw checkout directly, bootstraps the minimum local config so the gateway can run immediately, and then starts the native Gateway watcher and live UI in the foreground by default. `--root` lets you choose the environment location. While a foreground dev session is active, `ocm @<env> -- ...`, `ocm env run <env> -- ...`, `ocm env resolve <env> -- ...`, service resolution, and `ocm env exec <env> -- openclaw ...` use the same source checkout and run `node <checkout>/openclaw.mjs` directly instead of rebuilding through the package script. `--service` installs and starts the dev env in the OCM background service instead of keeping the process in the current terminal. If a dev env is already running in the background, `--watch --force` temporarily takes it over for the watch session and restores the background service when watch exits unless a later service policy request supersedes the takeover. For an existing runtime or launcher env, `--repo <path> --watch --force` temporarily runs that source checkout against the env's real root, config, state, and port without changing its binding, tees foreground output to the env gateway logs, then restores a running background service when watch exits unless a later service policy request supersedes the takeover. `--onboard` runs local onboarding first and then starts the dev gateway. For a new env, `dev` uses the explicit `--repo` checkout or the checkout enclosing the current directory. Outside an OpenClaw checkout, pass `--repo`; `dev` does not select a neighboring or previously remembered repository. Existing dev envs continue to use their recorded source.
`--no-ui` runs the Gateway watcher alone. `--no-watch` keeps the live UI with a
Gateway that does not rebuild automatically. Combine both for a plain foreground
Gateway. `--watch` and `--ui` remain accepted; each conflicts with its negative
counterpart. `--force` requires backend watching and rejects `--no-watch` or
`--service`.
All foreground combinations support `ocm dev stop <env>` and reuse a matching
active session. `dev status` reports backend watching separately from session
ownership.
Creating or changing a dev binding is refused while an environment containing or
owning its source, worktree path, or required Git metadata is busy with another operation.
Required Git metadata includes linked `objects/pack` directories and pack files, and object stores
referenced by `objects/info/alternates`,
including shared clones, transitive references, and initialized submodules declared
in `.gitmodules` (including nested submodules). Removing a containing environment
refuses while another registered source depends on that storage. Independent clones
with their own objects remain removable.
This also applies to local upgrade simulations; retry after that operation finishes.
Unchanged source bindings remain writable during restore and recovery.
Storage protection also follows loose-object directory and file symlinks,
including links introduced after registration. OCM streams the entries in Git's
loose-object directories and retains alias dependencies; ordinary object writes
do not change source identity or consume the dependency budget. This inspection
takes time proportional to loose entries and repeats at lifecycle rechecks, so
large loose stores can make admission and cleanup slower. Aliases within these
directories are protected conservatively, including missing targets during
cleanup; an unresolvable alias can prevent source admission. This protection
does not certify file symlinks for every Git clone or maintenance operation.
To keep a borrowed dev environment while explicitly changing its source checkout:
```bash
ocm dev stop shaks
ocm dev rebind shaks --repo /path/to/next-openclaw
ocm dev shaks --repo /path/to/next-openclaw
```
If stopping the foreground session restores a background service, also run
`ocm service stop shaks` before rebinding. Rebind requires completed foreground
ownership and stopped background ownership; it never stops processes itself.
It works even if the previous checkout is missing, preserves conversations,
configuration, credentials, workspace, reserved Gateway/UI ports and service
policy, and starts or installs nothing. Both checkouts remain untouched. Prepare
the selected checkout's dependencies and artifacts explicitly before starting dev.
User and plugin settings, including external plugin paths, remain unchanged.
Only existing borrowed dev environments are supported; legacy OCM-owned sources
and runtime or launcher bindings are refused. Validation or publication failure
preserves the old binding. Repeating the same canonical target is a validated
no-op. `--json` reports `envName`, `previousSourceRoot`, `sourceRoot` and `changed`.
Ordinary `dev` and `--force` retain their existing meanings and cannot switch a
binding. A later explicit service start resolves the new source; stale captured
service plans cannot start the old checkout.
New dev environments receive a private Gateway token in their initial config before
the environment is registered. The token remains stable through restarts and
source rebuilds, so paired clients can reconnect. Initialization never replaces an
existing config or its auth/SecretRefs. Repeating minimum setup leaves an unchanged
config untouched.
Foreground `dev` runs OpenClaw's native Vite server beside the Gateway by default;
use `--no-ui` to disable it.
OCM prints the session's UI address, then its initial native owner link after
both Vite and the Gateway Control UI document are ready. The native handoff keeps
the Gateway identity and credentials; only the browser document moves to Vite.
UI requires a local HTTP Gateway with Control UI enabled and installed UI dependencies.
For a templated `gateway.controlUi.basePath` such as `${UI_BASE}`, OCM reads the
effective path through the selected checkout's native config command. OpenClaw
resolves its environment, `.env` files, and config-provided variables; OCM keeps
that read private and leaves the authored config unchanged. An unresolved
placeholder is an error: supply its value or use a concrete path before retrying.
The resolved target stays captured for the session, including repeated starts
from terminals with different environment variables. Literal paths need no
additional config command.
`--service` uses the background workflow without foreground watching or UI and
rejects explicit `--watch` or `--ui`.
The controller owns Gateway, Vite and each dashboard helper. A component
exit stops its sibling; `dev stop` stops both and gives a running helper only the
remainder of its original 30-second budget. A late link is discarded, and uncertain
cleanup retains ownership. On Linux, macOS, and Windows, repeating the matching
command requests a fresh native owner link from that controller while keeping Gateway,
Vite and their address unchanged. One helper runs at a time; busy or unready
requests report a pending link. Requests have a 30-second deadline, and a caller
that exits or times out cannot redirect its eventual grant to another terminal.
Older OCM controllers retain address-only reuse and report fresh links as
unavailable until that dev session is restarted.
The UI address is retained across stop/start for the same environment. If that address is occupied
or reserved, startup fails until it is free. Cloned and imported environments
select their own addresses; restore keeps the current environment's address.
Stop the session before changing UI mode.
If you already have a plain `~/.openclaw` home you care about, use `ocm migrate <env>` instead of starting fresh. `setup` and `start` now point that out when they detect an existing plain OpenClaw home.
After an abrupt background daemon exit, a replacement preserves unresolved service ownership instead of starting another child for that environment. Inspect it with `ocm service recover <env>` after stopping its service intent. Recovery requires the displayed exact-claim token and your explicit confirmation that all old processes stopped; it never kills processes or restarts siblings. See [retained service ownership recovery](docs/USAGE.md#retained-service-ownership-recovery) for the checks and limits.
## Common paths
### Use the latest stable release
```bash
ocm start mira
ocm @mira -- tui
```
This is the shortest path for most people.
### Update OpenClaw later
```bash
ocm upgrade mira
ocm upgrade --all
ocm upgrade mira --dry-run
ocm upgrade history mira
ocm upgrade rollback mira --dry-run
ocm upgrade rollback mira
ocm upgrade simulate mira --to 2026.4.20
ocm upgrade simulate mira --to 2026.4.20 --scenario all
ocm upgrade simulate mira --to beta --scenario all
ocm upgrade simulate mira --to ./openclaw
```
On Unix, `ocm upgrade job start mira --json` starts an independent OCM worker and returns its request ID before the upgrade runs.
Use `ocm upgrade job status mira --request-id <id> --json` to reconnect to that exact request, or omit `--request-id` for the latest job.
Clients can copy `bindingKind:bindingName` from `ocm upgrade job capabilities mira` into `start --if-binding <kind>:<name>` to reject a binding change before the upgrade runs.
The worker uses the ordinary upgrade checks, checkpoints, and recovery for the environment's binding, and continues when the requesting terminal or managed Gateway exits.
See [asynchronous upgrades](docs/USAGE.md#asynchronous-upgrades) for result and interruption behavior.
Supported source launchers can update their checkout in place through the same no-target command on Linux and macOS.
OCM preserves the source binding and uses native source artifact reporting, update execution, and recovery.
Older checkouts without native source observations remain `local-command`, with support reported as unknown.
See [source upgrade behavior and recovery](docs/USAGE.md#upgrade-one-environment) for compatibility and checkpoint limits.
Live upgrades and rollbacks require a completed foreground dev session. Request
shutdown of recorded ownership with `ocm dev stop <env>`. Older watches without
an unfinished ownership record must be stopped from their original dev terminal.
Unreadable or unverified ownership
requires verified operator recovery, including checking the watch processes and
service policy. OCM preserves environment state, runtime files, and upgrade
history while refusing those operations.
`upgrade` stages the target runtime, validates the checkpoint source, and
prepares runtime recovery while the current managed gateway remains available.
Preparation failures leave the source environment and service unchanged. OCM
stops a running gateway only for checkpoint capture, runtime publication,
environment mutation, and OpenClaw update finalization. If a running service
cannot be restarted or started after the change, OCM keeps the restored
checkpoint and previous runtime as the coherent rollback state. A running
managed service is considered recovered only
after its HTTP health endpoint responds and OpenClaw's gateway status proves the
gateway is reachable; otherwise the upgrade follows the normal rollback path.
By default, checkpoints preserve the complete environment root, including credentials,
browser profiles, plugin payloads, unknown future directories, modes, symlinks,
and SQLite sidecars. OCM verifies tree contents and SQLite integrity before
publishing the checkpoint. APFS uses copy-on-write clones when available;
other filesystems use a metadata-preserving full copy. For standard OpenClaw
node/gateway stdout and stderr logs under `.openclaw[-profile]/logs`, APFS
verification accepts the captured bytes only when they exactly match a prefix
of a stable clone of the same live file. Post-capture appends need not stop an
independently managed node. Logs are retained, not excluded; rewrites, unsafe
rotation, mode changes, SQLite (even at a log path), and all other state still
require strict verification. Full-copy checkpoints remain exact. Restore discards only
explicit process residue such as locks, sockets, PIDs, and temporary runtime
directories. Legacy tar snapshots remain readable.
If a workspace contains projects that OpenClaw does not migrate, declare their
directories as independent before upgrading:
```bash
ocm env set-independent-paths mira .openclaw/workspace/projects
```
Explicit declarations also support `.openclaw/worktrees` and non-hidden
development directories elsewhere in the environment home. Other hidden
home/state namespaces, including credentials and the state database, stay protected.
Upgrade checkpoints then omit those directories without reading their contents,
and rollback restores the surrounding owned state while leaving those directories
in place. The list is explicit and empty by default; names such as `node_modules`
never imply ownership. Whole workspaces and configuration files cannot be excluded.
Memory, identity documents, and legacy migration inputs remain covered unless
they belong to a directory explicitly declared independent. Declarations require
operator knowledge of migration ownership: OCM does not prevent OpenClaw itself
from writing to these directories. See [checkpoint scope](docs/USAGE.md#upgrade-checkpoint-scope)
for the contract and limitations. Separately requested `env snapshot create`
backups still include the entire environment.
On APFS, snapshot preparation clones the bulk tree while the gateway is running.
The final service pause reconciles changed or removed entries and checks changed
SQLite state before publishing the checkpoint. Failed or displaced preparation
trees are cleaned up after service restoration or upgrade completion, not before
restart. Other filesystems retain the fully verified copy path.
Checkpoints contain secrets and share the source filesystem. Keep `OCM_HOME`
private, allow enough space for checkpoint divergence plus a restore candidate,
and retain an off-disk backup for disaster recovery.
A symlinked environment root is resolved for capture so the checkpoint contains
independent bytes; links inside the root remain links. Restore replaces the
registered root entry with the captured directory. If that entry is a symlink,
its former backing directory is left untouched. Older tree checkpoints whose
artifact is itself a symlink are refused on restore: they did not retain
historical contents. Create a new snapshot to protect the current contents.
Snapshot removal validates that the stored environment, snapshot ID, and
artifact path match the named snapshot before deleting anything. It takes the
live metadata and checkpoint out of service together, then reports warnings if
linked upgrade recovery or staged artifact cleanup still needs attention.
When both OpenClaw versions are known, `upgrade` rejects an older target before
creating a snapshot, downloading the target, or changing runtime metadata.
Switching only the binary cannot reverse newer OpenClaw config or SQLite state
migrations; returning to an older release requires a checkpoint of its owned state captured
while that release and its state schema were active.
After restarting an installed OpenClaw package, or restoring a recognized source launcher during upgrade rollback, OCM compares the bound artifact's build ID with the running Gateway's build ID when both are available.
A mismatch fails verification and follows the upgrade's rollback policy, even when the reported versions match.
Older packages, source artifacts, and status responses remain supported; when the artifact has a build ID but the Gateway cannot report one, the verification note says that running build identity is unavailable.
Source verification reads the current checkout's build metadata without inspecting Git or rebuilding it.
It does not prove that historical source contents were preserved or that an in-place source rollback is safe.
Launcher bindings retain their existing version and readiness checks.
`ocm upgrade history <env>` lists completed upgrade transactions newest first,
including source and target bindings and versions, the pre-upgrade snapshot,
migration/finalization status, service state, and rollback outcome. History is
stored as atomic JSON metadata under `OCM_HOME`; it does not copy config
contents, command output, or credentials. A successful in-place update of a
managed runtime retains the previous runtime files beside its transaction
record. Runtime backup and restoration preserve Unix directory modes, so recovery
continues to match its recorded integrity digest when the command's umask changes.
Removing or pruning the corresponding pre-upgrade snapshot removes
those retained files; switching to a different runtime does not duplicate the
source runtime.
During an active upgrade or rollback, OCM also retains the previous runtime's lock until recovery or successful completion settles.
Concurrent runtime removal or replacement waits, then rechecks current bindings; a runtime restored by rollback remains protected, while an unbound previous runtime becomes removable after successful completion.
On macOS and Linux, native upgrade commands retain this protection if they outlive the OCM process.
This temporary custody does not preserve unbound historical runtimes after the transaction and its native commands have ended.
`ocm upgrade rollback <env>` restores the newest completed upgrade or rollback
transition that has not already been reversed. Use `--transaction <id>` to
select a specific transaction and `--dry-run` to validate it without mutation.
Before creating a safety snapshot, rollback requires the current binding,
OpenClaw version, and service policy to match the selected transaction target;
it also verifies the recorded snapshot, source runtime or launcher, and any
same-name retained runtime recovery. A real rollback creates a `pre-rollback`
safety snapshot and a linked history transaction before it stops a managed
service or replaces runtime bytes. If restore or verification fails, OCM puts
the pre-rollback runtime and environment state back. Rolling back the linked
transaction safely reverses the rollback.
If rollback itself fails, OCM retains the pre-operation runtime files and snapshot and reports recovery as unresolved.
Use `ocm upgrade history <env> --json` to inspect the transaction, its snapshot, and retained runtime recovery metadata.
Preserve the locations printed in the failure result when metadata could not be written.
Do not remove those files or prune the snapshot until operator recovery is complete; retained files are evidence for recovery, not proof that the environment or service was restored.
This does not add automatic recovery after abrupt process loss.
Dev environments retain their current source binding during restore.
Manual snapshot restore also keeps their current runtime/launcher binding;
upgrade rollback restores the recorded runtime/launcher instead.
Once an environment is bound to a runtime, direct `runtime update`,
`runtime install --force`, `runtime build-local --force`, and `runtime remove`
operations reject that runtime.
This also protects managed files used through a registered runtime alias, even while the environment is stopped.
An in-place upgrade or rollback refuses when another environment depends on those files through an alias.
Use `ocm upgrade <env>` so the environment gets the snapshot, OpenClaw migration, rollback, and verification path, or clear the binding first when intentionally managing an unused runtime.
An idle alias with no environment binding still permits replacement or removal of its backing runtime.
Runtime package and companion installation preserves the caller's npm settings,
including script policy and home-relative configuration. OpenClaw lifecycle
state uses a disposable directory, and inherited service state paths are cleared
so installation cannot discover the caller's OpenClaw state through those paths.
For unreleased OpenClaw workspaces, `runtime build-local` follows the complete
transitive closure of private `workspace:*` packages. It rewrites nested
workspace specs only inside scratch archives before installation; the source
checkout remains unchanged.
For unreleased source builds with separately published, version-bound official
plugins, repeat `runtime build-local --companion <plugin-id>`. OCM packages each
selected plugin through OpenClaw's own package-local release contract, requires
exact host-version parity, stages it as a runtime-owned bundled plugin with
isolated dependencies, and records artifact and entrypoint hashes for runtime
verification.
`upgrade simulate` clones the source env, leaves the real env untouched, and
cleans temporary simulation envs and runtimes when the run finishes. For
published targets it first validates that the target exists, then runs OpenClaw's own
`update --dry-run --json` plan against the clone, switches the clone, and runs
update-mode doctor, plugin update dry-run, and gateway status checks. For local
repos it validates the checkout with dependency/build checks before running the
same post-update checks. Use `--scenario all` to test the current env config
plus built-in clean minimum and Telegram-configured env shapes. Use
`--keep-simulations` only when you need retained simulation envs and temporary
runtimes for debugging.
### Use a local checkout or dev build
```bash
ocm dev luna
ocm dev luna --root ~/scratch/luna
ocm dev luna --no-ui
ocm dev existing-env --repo ~/src/openclaw --watch --force
```
Use `ocm dev` when you want to run your checkout with separate environment state and a gateway port, or when you want to temporarily run source against an existing env in watch mode without rebinding it. While a foreground dev session is running, OCM's OpenClaw-running commands for that env resolve to that source checkout, so one-shot checks use its built `openclaw.mjs`. OCM refuses background service installation, start, and restart for that env until the foreground session exits; a running service taken over with `--watch --force` is restored by the watch session after its source processes stop only if its service policy has not been superseded. Foreground output is saved under that env's `.openclaw/logs/` directory, so `ocm logs <env>` remains useful while the foreground Gateway is running. If you are already inside an OpenClaw checkout, `ocm setup` can detect that and suggest a local path automatically.
On Unix, foreground Node commands wait until OCM records their process ownership before executing source or `NODE_OPTIONS` preload hooks. The gate preserves the command arguments, terminal input, and configured Node options after release.
Before starting a new foreground session or service preparation, OCM checks that a running background daemon uses
compatible ownership locks and that its runtime record identifies the current
process. A daemon whose compatibility cannot be verified must finish starting
or be refreshed before the session can claim ownership. During a maintenance
window, run `ocm service refresh-daemon --acknowledge-gateway-restarts` from the
updated OCM installation; this restarts managed gateways. Package version alone
does not establish compatibility. A confirmed stopped or unloaded daemon does
not require refresh, and existing session reuse and stop remain available.
New dev environments borrow the exact selected main checkout or registered linked
worktree, including its tracked edits and untracked files. OCM creates no Git
worktree for them. Their environment state stays outside the source and its Git
metadata. A borrowed environment resumes its recorded canonical source path;
an explicit `--repo` or another enclosing checkout cannot rebind it. Restore a
missing source, changed path alias, or invalid Git registration before retrying.
An existing OCM-owned dev env resumes its recorded worktree, preserving its uncommitted changes. If that worktree is missing or has been replaced by an unrelated checkout, `dev` reports an error instead of recreating it; restore the recorded checkout before retrying. An explicit `--repo` must still identify the env's original repository, including equivalent path aliases, and cannot rebind the env to another checkout.
Environment commands and Gateway resolution apply the same check when selecting
the dev source, including routing through an active source watch. Saved service
plans also validate the recorded checkout before starting it. Restore the
recorded checkout before retrying. Explicit runtime or launcher overrides and
status inspection remain available. A worktree validation failure leaves config unchanged.
Before starting source, `dev` checks the installed entry points for the tooling declared by that checkout. It reuses hoisted or isolated installs whose tooling resolves. New borrowed environments and OCM-owned dev worktrees can prepare missing tooling with `pnpm install --frozen-lockfile` and check it again. A resumed borrowed environment reports missing tooling so you can prepare its checkout explicitly; it does not reinstall dependencies. Source takeover of a runtime or launcher env only validates the borrowed checkout and fails before stopping its service if preparation is needed. OCM does not reinstall through linked dependency directories. A modules-directory environment override may select dependencies inside that checkout, including before OpenClaw creates its `node_modules` link. This also applies to default UI startup: its prerequisite checks accept hoisted packages and pnpm UI package links through the deferred root link. OCM inspects the configured tree without creating that link and rejects overrides or UI packages that resolve outside the checkout. When the link is absent, OCM starts the native source first and holds the UI until the link is ready, failing on cancellation, source exit, or a 30-second timeout. Suspending the foreground source also suspends OCM and pauses that startup timeout until resume. These are startup checks; OpenClaw still owns builds and validation of the running application.
Direct dev-source commands run with `NODE_DISABLE_COMPILE_CACHE=1` and without
`NODE_COMPILE_CACHE` before Node starts. This avoids OpenClaw's compile-cache
bootstrap wrapper, which can convert a child's termination signal to an ordinary
exit code. Other `NODE_OPTIONS` still pass through, and OpenClaw's native runners
continue to own rebuilds and auto-doctor.
Foreground dependency installation keeps build output and pnpm diagnostics readable while using lifecycle reports to check script completion. When run from a terminal, installation keeps interactive stdin while streaming that output. On Unix, interrupted or unfinished build scripts retain foreground ownership even if pnpm returns an ordinary error or an optional build lets it succeed. Completed installation errors remain retryable.
Repeating `ocm dev <env>` with the same effective backend watching/UI choices and source returns its status and existing gateway link without preparing dependencies, onboarding, or restarting processes. Mode/source/root/port mismatches and onboarding during a foreground session are errors. Startup and service restoration are reported as progress; an invocation during startup does not claim a source identity that has not yet been published. Temporary runtime or launcher takeovers retain the `--repo <path> --watch --force` form. Active status and routed source commands use the captured launch root and port even if config is edited; an explicit different port is refused. Watch sessions started by an older OCM without endpoint metadata need to be stopped from their original terminal and started again before they can be reused. Only the foreground invocation that acquires the lease prepares configuration.
Temporary source takeovers capture the canonical checkout before preparation.
Retargeting a selected path alias leaves the active worker and routed commands
on that checkout; stop the session before selecting the new alias target.
Aliases that still identify the active checkout can reuse the session.
Use `ocm dev status [env]` to inspect dev environments and temporary source watches on runtime or launcher environments. It reports the source path, gateway URL, and session ownership (`starting`, `active`, `restoring`, `inactive`, or `unknown`). Active foreground ownership can outlive the wrapper process and does not imply that the Gateway is ready. JSON reports backend watching as `sourceWatch.watching`, keeps `serviceRunning` separate from the saved `serviceDesiredRunning` policy and includes the watch PID, start time, and any inspection issue. `gatewayPortReachable` uses a 100 ms loopback TCP check; an open port does not establish Gateway identity or readiness. Status leaves watch metadata unchanged and omits lease tokens.
Named status and JSON/raw output also report `gatewayHealthReady` from `/health` and `ui.processRunning`/`ui.httpReady` for the recorded UI process and HTML document. Active sessions use their captured Gateway endpoint. UI readiness stays unknown when ownership cannot be verified; `ui.issue` explains the observation. The existing `uiUrl`/`ui_url` field retains the basic address of an active UI session.
Use `ocm dev stop <env>` from another terminal to cancel an owned plain or watched foreground session, including dependency preparation and onboarding. It waits for the source processes to stop and restores a background service previously taken over with `--watch --force` only while the takeover's observed policy revision remains current. A later `service stop` or `service uninstall` is preserved, including during recovery of sessions that recorded the takeover revision. The environment, configuration, source checkout, and dependencies remain available for the next run. `--json` reports `envName`, `stopped`, and `serviceRestored`; repeated stops after completion are harmless. Independently managed background services keep their existing stop commands.
`ocm dev <env> --service` owns dependency preparation and onboarding until their
processes finish. `ocm dev stop <env>` can cancel that preparation while keeping
an already-running managed Gateway and its launch plan intact. Sibling service
updates defer changes and restart requests for that Gateway until preparation
ends; an explicit service stop or uninstall still takes effect. Successful
preparation rechecks the environment, source binding, and service policy before
starting the service. Repeating `--service` with an unchanged binding avoids an
install/stop/start cycle.
For new Unix foreground generations, output readers must finish before OCM clears child ownership. A read failure, missing output completion, raw termination signal, or lost controller retains an unfinished session. Stopping a matching process group alone cannot prove detached workers stopped; subsequent stop, watch, service-start, and destroy requests preserve that uncertainty. Ordinary acknowledged errors remain retryable after output completes. Onboarding keeps real terminal output: unsuccessful or cancelled onboarding without observed output remains unfinished, while successful interactive onboarding still works. Released legacy watch records retain their existing recovery rules, and Windows keeps its process-job cleanup proof. Unknown or pending ownership still requires operator verification. Use an updated OCM CLI and refresh an incompatible running daemon before starting a new foreground generation; updating files does not refresh an old process.
After independently verifying that **all source processes, including detached workers, have stopped**, recover a retained cleanup failure with `ocm dev stop <env> --acknowledge-stopped-processes`. OCM still refuses a running controller, recorded child or process group, a held lease, unpublished child ownership, or changed environment/process scope. Recovery releases only the matching failed session; it preserves source, config, and current service policy without signaling processes or restarting a background service. You can then retry dev or remove the environment normally. Start a background service separately if needed. An empty process group by itself is not enough to make this acknowledgement.
`ocm env destroy <env> --yes` stops the recorded foreground generation and verifies shutdown before removing the environment. It rechecks the binding after stopping and preserves state if another owner or binding appears. While a watch is running, previews defer the changing process-tree inspection until after shutdown (`processInspectionDeferred` in JSON). `env remove` and `env prune` refuse active or unfinished watches; stop those sessions first. A guarded destroy with `--if-state-token` also requires `dev stop` followed by a fresh preview, so its original state guarantee remains intact. Completed watch records are removed with the env; synchronization lock files remain reusable.
New environment roots must be separate: a root cannot equal, contain, or sit
inside another registered environment root, including through path aliases.
Creation, cloning, import, and other commands that create an environment reject
overlap before writing environment state, regardless of protection flags.
Default sibling roots and disjoint custom roots remain valid.
These operations also reject roots that overlap registered dev sources,
including source and destination aliases. Missing borrowed paths
remain reserved until their binding is removed. Removing a borrowed environment
preserves its source, dependencies, generated output, and unrelated source workers.
Restore and rollback also preserve borrowed source and known Git metadata;
checkpoint exclusions must cover the affected paths, including missing source
reservations.
Restore and rollback also refuse to replace another registered environment's
root or the links needed to reach it, including legacy nested registrations.
A scoped checkpoint is safe only when its saved exclusions preserve the entire
other environment and its access paths; excluding just part of it is insufficient.
When a managed daemon is running, it must support new or changed borrowed
bindings before registration. Older OCM readers refuse these records. Refresh an
incompatible daemon with the command above; unchanged bindings and confirmed
stopped or unloaded managers remain usable.
Health cleanup, removal, pruning, destroy, and simulation cleanup preserve other registered and active temporary dev sources and the Git metadata they need, even with `--force`. Remove dependent dev environments, or stop temporary sessions with `ocm dev stop <env>`, before deleting their containing environment or worktree. Preparation rollback also preserves these sources when publishing a newly created worktree's binding fails. The error reports the original failure and the retained worktree path; stop the dependent temporary session before removing that worktree.
### Try beta or pin a specific release
```bash
ocm start rowan --channel beta
ocm start ember --version 2026.3.24
```
### Inspect an existing plain OpenClaw home before migrating it
```bash
ocm migrate mira
ocm migrate mira /path/to/.openclaw
ocm adopt inspect
ocm adopt plan --name mira
```
`migrate` is the simple front door for existing OpenClaw users. It imports a plain OpenClaw home into a managed env in one step.
`migrate` preserves config, auth, sessions, logs, and other durable user state, rewrites env-scoped paths for the new managed root, and clears only live runtime residue like locks, pid files, and sockets. If `openclaw` is already available on `PATH`, it also binds the imported env to an env-local migrated launcher so you can keep using it through OCM immediately.
Legacy configuration, system-agent, and Crestodian audit files retain their original
bytes, including migrated archives and recovery files. Their historical paths stay
unchanged so OpenClaw can verify its existing audit checkpoints. OCM excludes these
paths from copied-runtime-reference diagnostics. This also applies to `adopt import`.
Skill Workshop bundles also retain their original bytes, including drafts, support
files, proposal metadata, and rollback receipts. OpenClaw owns their stored hashes
and target relocation; OCM preserves the historical paths and excludes them from
copied-runtime-reference diagnostics.
Saved skill-library revisions under `.openclaw/skill-library` retain their payload
bytes and file modes during clone, migration, and state-inclusive archive import.
OpenClaw owns their manifest hashes and revision identity; embedded paths remain
authored content rather than runtime references. Cleanup and copied-reference
diagnostics preserve the same ownership. Archive export copies protected SQLite
payloads and their supporting files verbatim rather than snapshotting them.
A config include that needs rewriting inside a protected payload causes the copy
to fail and roll back; move that active configuration to a mutable include outside
the published revision. Unchanged includes remain supported. Ordinary runtime paths still
relocate and volatile process state follows each command's existing cleanup policy.
Migration refuses an active state database that resolves to protected history and rolls back the partial import; passive history and ordinary unprotected database aliases remain supported.
When a configured agent workspace is a repository checkout outside the plain
OpenClaw home, including through a symlink, migration copies that workspace into
the new environment and rewrites the imported config to use the copy. The source
home and repository remain unchanged.
Agents using identical or nested workspace folders retain that sharing in the copy, including configured aliases of the same folder.
Aliases of the source home remain supported; workspace links inside that home are checked before their paths are projected into a shared copy.
Each maximal configured external folder is copied once; nested workspaces use the corresponding subfolder, while unrelated folders remain separate.
For identical roots, the default workspace destination takes precedence, followed by agent ID order.
An outer workspace that contains the plain home also supplies the copied agent workspace locations inside that home; runtime state still lives in the managed environment's `.openclaw` directory.
The copy of the home inside that outer workspace is ordinary workspace content, not a second active runtime home.
Protected history from the original home remains byte-preserved in that copy as well.
Retained SQLite session locations, in-home legacy session headers and managed Git worktree bindings follow these workspace projections; active in-home database references keep using the fixed state directory.
Worktree IDs and checkout content are preserved, and required Git storage must already exist in the copied files; a relocation failure rolls back the import.
Config `$include` files still must remain inside the plain home because OCM does not take ownership of external config.
If migration reports a `copied destination symlink`, it refuses the workspace copy and removes the partial import.
The diagnostic names a destination inside that removed import; inspect the matching `workspaces/...` path in the original plain home to locate the conflicting link.
Retry from a separate copy of the plain home, removing only the conflicting symlink in that copy and leaving its path absent so migration recreates the correct file or directory.
Keep the copy's configured external workspace paths pointed at the intended source workspaces.
Keep the original home and linked external data intact; do not remove the link's target directory or its contents.
Environment clone, export, and import flows preserve managed OpenClaw plugin
payloads under the legacy, extension, npm, and Git install roots. Clone and default archive
import clear legacy file-based sessions, logs, backups, and process residue so the new
environment does not share active runtime state with its source. New clones also
retain shared managed skills under `.openclaw/skills` and their global ClawHub
tracking metadata under `.openclaw/.clawhub`; ordinary runtime-state cleanup retains
these roots too. Clones also clear copied agent database process leases while keeping the state database,
durable rows, and source leases unchanged.
Default import refuses configured active databases inside protected history and removes the partial target before registration, including for archives without source-root metadata.
Use `ocm env export <env> --include-state --output <archive>` to export this
environment as the same installation, then restore it with
`ocm env import <archive> --name <new-env>`. The flag retains every file under
the environment root, including OpenClaw state, plugin payloads and dependencies,
sessions, and unrelated or legacy data. It excludes non-durable process files
and rebuildable runtime debris using the snapshot rules. SQLite databases
anywhere under the root are captured as coherent committed snapshots, including
WAL writes; raw database sidecars are omitted. Each database is captured
independently, not as one transaction across the environment.
New archives, with or without `--include-state`, retain the accepted source root and its captured canonical path in optional `env.canonicalSourceRoot` metadata.
Configuration relocation uses both recorded roots without requiring the original source or alias to exist; state-inclusive runtime-reference relocation uses the same identities.
Older archives retain their existing source-root matching rules.
The archive format remains version 1, and older readers ignore the optional field.
Source identities may use POSIX, Windows drive, or UNC syntax; the extension preserves acceptance of portable foreign-platform contents without adding translation of platform-specific payload paths.
On Windows, ordinary drive/UNC and extended-length spellings of a recorded root relocate together.
State-inclusive export copies configuration files verbatim. Import rewrites
env-scoped OpenClaw config paths for the new root, including agent workspaces
and agent directories, through the same rules as an ordinary import. It also
assigns the new gateway port and resets the sandbox origin. Configuration must
be valid; includes that own agent workspaces or the sandbox origin must be
flattened first, as for ordinary imports. No OpenClaw runtime is required.
State is preserved; references to the environment root are rewritten to the
new root. Import rewrites text values across registered OpenClaw SQLite databases,
including session metadata, recorded file paths, worktree records, and plugin
receipts, plus the runtime JSON/JSONL and text files handled by plain-home migration.
It retains sessions, logs, leases, and other durable state. Unchanged values and
binary payload columns (including compressed records) retain their bytes. Other
workspace files and integrity-protected history also retain their bytes.
Import refuses a selected active database that resolves to protected history and removes the partial target before registration, instead of preserving stale runtime state or changing historical bytes.
Unselected history and ordinary unprotected database aliases remain supported.
The ownership check also applies when restoring to the original root or importing an archive without source-root metadata.
Authored Board tabs and widgets retain their content, checksums, and associated metadata unchanged, even when their text mentions the original environment root.
Every other file outside the config and state-reference rewrites stays byte-identical to the archive.
Migration and state-inclusive import share root-reference matching for plain
paths, file URLs, and existing runtime text. A root must end at a path component
boundary; sibling names that share its prefix remain unchanged. On POSIX,
backslashes in filenames are not directory separators. References outside the
source environment root are left unchanged; external contents are not exported
and may need separate preparation after moving.
Import refuses to update a database outside the copied root; internal database
links are retained.
Owned file and directory links use relative targets in the archive; external
and dangling links retain their targets without copying external contents.
Import relocates selected Git repositories and linked worktrees to the destination before registering the environment.
Their required Git storage must be present inside the copied archive; an incomplete graph or unresolved copied lock fails import and removes the incomplete target without modifying the archive or source.
Git indexes, branches, snapshot refs, authored files, and protected history retain their contents.
Use `--include-state` when managed-session registry continuity is needed: ordinary archives still omit `.openclaw/state/openclaw.sqlite` and only retain their existing selected files.
State-inclusive archives are created with private access. Import preserves
directory modes under a private environment root and leaves it stopped;
export leaves the source unchanged.
Archive ownership and extended ACLs are not transferred; the private root
prevents broader access when those restrictions cannot be reproduced.
An explicit `env import --sandbox-origin` still replaces that setting.
Export JSON reports `includeState`; its human summary also reports whether
state was included. State-inclusive import reports `configPathsRewritten: true`
and `statePathsRewritten` in JSON; the latter says whether any state references
changed. `databasePathsRewritten` maps each processed database path relative to
the imported root to its count of changed text values; zero means no values
changed. The human summary includes these counts. Export without the
flag and imports without included state retain their existing selection,
configuration rewriting, and cleanup behavior.
Clone and imports without state reject symlinks or non-directory entries at `.openclaw`, `.openclaw/agents`, and `.openclaw/extensions` before rewriting or clearing copied state, preserving the source and leaving the target unregistered.
Clone and imports without state remove unconfigured agent directory links from the copy without changing their linked source data.
Configured agent directories inside the environment retain their payloads through clone and ordinary export/import; configured external or symlinked directories are rejected.
Equivalent accepted and canonical environment-root spellings preserve the same configured agent payload, including agent directories nested in otherwise temporary locations.
Clone (including upgrade simulation), `migrate`, and `adopt import` use SQLite snapshots for recognized operational databases: shared state and quarantine, canonical agent stores, legacy `memory/*.sqlite` stores, and the default Workboard, Team Reports, Logbook, and active Matrix account state stores.
Agent database paths recorded in the source shared-state registry are also included when the existing copy traverses them.
Each database is a coherent committed snapshot; databases and other files are not captured in one atomic transaction.
The source stays running and its database contents are not rewritten.
Clone, default archive import, and upgrade simulation rebase retained SQLite session paths, including `sessionRoot` and `spawnedCwd`, from the source environment root to the copied root.
External paths and integrity-protected history keep their existing values, while clone continues to clear copied runtime residue and database leases.
Retained managed Git worktrees whose repository and required Git data are inside the copied environment keep their checkout content, including the default `.openclaw/worktrees` layout.
Clone relocates their registry identity and structural Git links together, preserving session/worktree IDs, branch and snapshot refs, indexes, and authored content.
It retains and relocates owned Git storage links needed by those checkouts.
It fails and removes the incomplete target when required Git data is missing or external, copied locks/run ownership remain unresolved, or a required Git write would change integrity-protected history; resolve the reported condition before retrying.
Clone does not copy external repositories, clear Git locks, or change source registrations.
Clone refuses an active database that resolves to protected history, including through directory aliases, and removes the partial clone before registration.
For clone, migration, and adoption, OCM does not classify a package or project
asset as operational merely because it has a SQLite header or filename.
Unregistered custom database locations and opaque package, project, import, audit, and Workshop payloads retain their existing copy behavior.
Symlinks keep their existing handling.
A selected database that cannot be snapshotted makes the command fail and invokes its existing target cleanup; raw source WAL or journal files are never attached to its snapshot.
Cloned plugin registrations use the clone's managed files. Copied local projects
and archives retain their original source information, and missing managed
payloads retain clone-owned records for independent diagnosis or repair.
Clone, import, and migration give the target environment a new local gateway and MCP app sandbox listener. They do not copy a public `mcp.apps.sandboxOrigin` because that URL belongs to the source environment's external routing and may still reach the source sandbox. Direct connections derive the target sandbox port automatically. For a target behind a reverse proxy or tunnel, pass its dedicated public origin explicitly:
```bash
ocm env clone source target --sandbox-origin https://target-apps.example.com
ocm env import ./source.ocm-env.tar --name target --sandbox-origin https://target-apps.example.com
ocm migrate target --sandbox-origin https://target-apps.example.com
```
If the config root, `mcp`, `mcp.apps`, or `mcp.apps.sandboxOrigin` is owned by OpenClaw's `$include`, flatten that section before clone, import, or migration. OCM fails closed instead of flattening include-owned configuration or leaving a copied source origin active.
`adopt inspect` and `adopt plan` are the explicit read-only preview tools. Use them when you want to inspect the plain OpenClaw home OCM would read or preview the target env/root before importing.
### Keep supervised envs visible
```bash
ocm service status
ocm logs mira --tail 50
ocm logs mira -f
```
Stopped envs remain installed even when the idle shared daemon is absent.
Use `ocm service start <env>` when you want to run one again; see
[service status and recovery](docs/USAGE.md#start-stop-restart).
OCM negotiates fresh-process restart support only when it executes an
`openclaw.mjs` entrypoint directly or through OCM's managed Node.js toolchain,
so the gateway PID is the process OCM owns. `ocm service status <env>` reports
`protocol v1` when OpenClaw can hand restart intent back to OCM atomically.
With that protocol, `ocm service restart <env>` asks OpenClaw to restart
immediately through its recovery handoff. OpenClaw records eligible active
sessions and subagents before exiting, OCM starts the replacement gateway, and
OpenClaw resumes that recoverable work after startup. This does not wait for an
in-flight turn to finish before replacing the gateway process.
External restart requests collect the native helper result while observing replacement for up to 30 seconds; a rejection fails the command even if the original Gateway remains healthy.
A pending helper or unobserved replacement produces a warning without forcing a supervisor restart.
Requests made inside the target Gateway remain asynchronous so the caller cannot block its own restart.
Package-manager, shell, host-Node, and other wrapper-backed bindings run in
legacy compatibility mode without OCM's native service identity or detached
respawn. `ocm service restart <env>` preserves their existing direct-supervisor
restart behavior and warns that in-flight work cannot be recovered. Bind a
directly invoked OpenClaw runtime to gain recovery-aware restarts. Use
`ocm service restart <env> --force` only to explicitly bypass a recovery
handoff that is advertised but unhealthy.
Delayed legacy or forced restart recovery activates the shared daemon only when the service manager confirms it is absent or stopped.
A failed or unknown observation fails the command with retry guidance, preserving healthy sibling Gateways.
The target restart request remains pending for the existing daemon.
## Why not just run OpenClaw directly?
Running OpenClaw directly is fine for the simplest case.
Use `ocm` when you want:
- more than one environment
- clean runtime and launcher separation
- stable and local-dev setups side by side
- inspectable supervised env gateways
- safer upgrades, snapshots, and repair flows
Manual setup works. `ocm` is what makes it feel organized.
On Unix and Windows, updates to an already-private OpenClaw config preserve its
private access. OCM creates the replacement privately and verifies protection
before writing data; files with other authored access rules keep the existing writer.
## Learn more
For the full guide, including scenarios and command details, see [docs/USAGE.md](docs/USAGE.md).
You can also use:
```bash
ocm help
ocm help dev
ocm help start
ocm help setup
ocm help env
ocm help release
ocm help runtime
ocm help launcher
ocm help service
```
## Platform support
Current support:
- macOS
- Linux
Background services:
- macOS uses `launchd`
- Linux uses `systemd --user`
Windows service support is not implemented yet.
## License
See [LICENSE](LICENSE).