> ## Documentation Index > Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt > Use this file to discover all available pages before exploring further. # Upgrading > Update NanoClaw and its skills with /update-nanoclaw and /update-skills — preview, backup, merge, validate, and restart. Don't update with a raw `git pull`. NanoClaw records each sanctioned upgrade in `data/upgrade-state.json`, and a startup tripwire refuses to boot if the running code's version doesn't match that marker. The supported path is the `/update-nanoclaw` skill, which handles the merge, validation, and the marker stamp for you. ## Updating NanoClaw Run `/update-nanoclaw` in a Claude Code session at your project root. The skill works in stages, and nothing is committed until you've seen a preview: 1. **Self-refresh.** It fetches upstream and refreshes its own skill folder first, so the newest update process runs the update. 2. **Preflight.** Stops if the working tree is dirty — commit or stash first. Adds the `upstream` remote if it's missing. 3. **Safety net.** Creates a backup branch (`backup/pre-update--`) and tag (`pre-update--`) before touching anything. 4. **Preview.** Shows upstream commits since your last sync and buckets the changed files: skills, host source (`src/`), container (`container/`, triggers a rebuild), and build config (lockfile changes trigger a dependency install). You then pick a path: full merge (default), selective cherry-pick, rebase, or abort. 5. **Conflict preview.** Dry-runs the merge (`git merge --no-commit --no-ff`, then abort) so you see which files would conflict before committing to anything. 6. **Merge and resolve.** Applies your chosen path. On conflicts it opens only the conflicted files, resolves the markers, and keeps your local customizations intact. 7. **Validation.** Runs `pnpm run build` and `pnpm test`. If `container/` files changed, it also rebuilds the container image with `./container/build.sh`. 8. **OneCLI pins.** If the `onecli-gateway` or `onecli-cli` pin in `versions.json` moved since your backup tag, the skill surfaces it and walks you through the OneCLI upgrade ([`docs/onecli-upgrades.md`](https://github.com/nanocoai/nanoclaw/blob/main/docs/onecli-upgrades.md)) before the restart — the gateway and CLI are external components, so the running versions must be bumped to match the merged code. No pin change and the step is skipped. 9. **Breaking changes.** Scans the new `CHANGELOG.md` entries for `[BREAKING]` lines, each of which names a migration skill (`Run / to …`); the skill lists them and offers to run the ones you pick. A breaking change that points to a `docs/` page instead of a skill is one you follow by hand. 10. **Skill updates.** Detects which channel and provider adapters are wired into the barrels and offers to continue into `/update-skills` — the per-skill selection happens there, not in the update itself. 11. **Marker stamp.** On success, stamps the upgrade marker (`pnpm exec tsx scripts/upgrade-state.ts set "" update-nanoclaw`) so the tripwire passes on next start. 12. **Summary.** Prints the backup tag, conflicts resolved, and the restart command for your platform. To roll back, reset to the backup tag the skill printed: ```bash theme={null} git reset --hard pre-update-- ``` ## What happens to installed channels Channel and provider adapters are files copied into your tree from the long-lived `channels` and `providers` branches — they aren't part of the `main` merge, so the update itself doesn't refresh them. Instead, after the merge, `/update-nanoclaw` detects which channels and providers you have wired into the barrels (`src/channels/index.ts`, `src/providers/index.ts`) and offers to continue into `/update-skills`, where you pick which ones to re-apply. Re-applying is safe and idempotent: it re-fetches the latest adapter files from upstream and overwrites only that skill's own code. Credentials in `.env`, barrel wiring, and database state are untouched. The flip side: if you edited an adapter file directly, re-applying overwrites your edits — commit first so the changes are recoverable, or skip that channel and update it manually. ## Updating skills To refresh skills without a full upstream update, run `/update-skills`. Its flow: 1. **Preflight.** Clean working tree, upstream remote confirmed, then `git fetch origin channels providers --prune`. 2. **Detection.** Reads the channel and provider barrels to list which code-carrying skills are installed. Operational skills (ones that copy no code into the tree) have nothing to refresh. 3. **Selection.** You pick which skills to re-apply. 4. **Re-apply.** Invokes each selected skill's own `/add-` apply, which fetches the latest files and overwrites the copied-in code. 5. **Validation.** `pnpm run build` and `pnpm test` — each channel and provider skill ships a registration test that asserts the barrel still registers the adapter. 6. **Container rebuild.** If a re-applied skill changed files under `container/` (e.g. a provider's in-container runtime), the skill rebuilds the agent image with `./container/build.sh` — until then new sessions keep running the old image, so the rebuild is what makes the change live, not the file copy. A channel-adapter-only refresh skips this. Restart the service afterwards to pick up the refreshed host code. ## Heavily customized forks If you've diverged far from upstream — many local commits, deep changes to core files — merging gets painful. `/migrate-nanoclaw` takes a different approach: it extracts your customizations into a replayable guide, checks out clean upstream in a worktree, and reapplies them on the new base, so there's nothing to merge. `/update-nanoclaw` suggests it automatically when it detects large drift. See the note in [Migrate from v1 or OpenClaw](/migrate-from-v1) for how it differs from the v1 migration path. ## When not to update * **Dirty working tree** — the skill stops; commit or stash first. The same applies before `/update-skills`. * **Locally modified adapters or upstream skills** — re-applying a channel skill overwrites its files; make sure your edits are committed so you can recover them. * **Just want to see what changed** — pick the abort option in the preview step. It shows the changelog and changes nothing. * **Large drift** — prefer `/migrate-nanoclaw` over a conflict-heavy merge. ## After an upgrade The skill validates the build and tests itself, but a few things are worth checking by hand: * **Restart the service.** Unit and label names are per-install; the skill prints the exact command (derived from `setup/lib/install-slug.sh`) for macOS, Linux, or a manual `pnpm run dev`. * **Container rebuild.** If `container/` changed, the image was rebuilt — running agent containers keep the old image until their session ends; new sessions use the new one. * **Send a test message** on each channel you use, and check `logs/nanoclaw.log` for errors. * **Tripwire trips on start?** The marker wasn't stamped (validation failed, or the update bypassed the skill). Fix the underlying issue, then stamp manually: `pnpm exec tsx scripts/upgrade-state.ts set`. If something is off, start with [Troubleshooting](/operate/troubleshooting).