taodengandClaude <claude-opus-4-8> <noreply@anthropic.com>
2ac3e7918c
Maintainer-approved P2 restructure. Principle: what a new user needs in the first
10 minutes stays in README; the operations manual moves to docs/. Content MOVED,
not rewritten — an independent verifier swept all 20 original sections, 60+
distinctive facts, and all table rows against the new corpus: zero content loss.
New files (verbatim moves + two mandated dedup merges):
- docs/lan-mode.md (396) — LAN setup, key management, quotas, anonymous access,
deployment/security model + honest limits, client connect
- docs/tui-mode.md (196) — full TUI section + the four giant env-cell essays as
prose subsections; opens with the single-user SECURITY
warning + the PAUSED billing-split status banner
- docs/troubleshooting.md (136) — full troubleshooting; canonical 401/credential-
isolation explanation (union of the 4 prior copies)
- docs/upgrading.md (79) — upgrade paths, snapshots, rollback, auto-sync
README keeps: pitch (byte-identical), new TOC, 62-line Quickstart, How It Works
verbatim (incl. #171 billing-status note + workload fit), the three release_kit-
pinned tables (Available Models / API Endpoints / all 37 Environment Variables
rows — 4 giant TUI cells now one-line pointers), All Commands, slim Troubleshooting
(bootstrap quirks retained per release_kit bootstrap_quirk_policy), summary stubs
linking each moved doc, Repository Layout (+4 doc rows), Governance, Support.
Dedup (canonical copies): sdk-cli vs subscription-pool table → docs/tui-mode.md;
credential-isolated-home / permanent-401 → docs/troubleshooting.md#tui-401.
Link retargets: docs/runbooks/615-canary.md, docs/runbooks/tui-flip-rollback.md,
setup.mjs (one banner string; node --check clean). 126 links across the touched
files verified resolving; repo-wide grep shows no reference to a removed anchor.
npm test: 332 passed / 0 failed.
Co-Authored-By: Claude <claude-opus-4-8> <noreply@anthropic.com>
3.7 KiB
Part of OCP — the full upgrade manual (ocp update paths, manual flags, rollback, and OpenClaw auto-sync). The README keeps a short stub with the one-liner.
Upgrading
The simplest path: ask your AI.
Paste this prompt:
Upgrade my OCP. Run `ocp update` and follow whatever it says.
If it tells me to run `claude auth login`, I'll do that.
What ocp update does:
- Patch bump (e.g.
v3.21.0 → v3.21.1): light path (git pull + npm install + restart). - Cross-minor (e.g.
v3.18 → v3.22): full path: pre-flight check, snapshot,setup.mjs(with plist env-merge), service restart, post-flight/healthand/v1/modelsverification. - Old version (< v3.4.0): fresh-install. Pre-v3.4 lacked admin-key/usage-db, so there is nothing to migrate. Your OAuth token (managed by the Claude Code CLI, not OCP) is preserved; you do not need to re-OAuth unless your token expired separately.
Snapshots are saved to ~/.ocp/upgrade-snapshot-<ISO-ts>/ and never
auto-deleted. Clean old ones with rm -rf ~/.ocp/upgrade-snapshot-* once
you're confident the upgrade is stable.
Manual upgrade — same command, no AI
ocp update # smart-pick path
ocp update --check # show available updates, don't apply
ocp update --dry-run # preview plan
ocp update --target v3.13.0 # pin a specific version
ocp update --rollback --yes # restore most recent snapshot (--yes confirms)
ocp update --rollback --list # list snapshots, no mutation
ocp update --rollback --dry-run # preview rollback plan
When upgrade fails
ocp update prints a recovery line on failure. To restore from the snapshot:
ocp update --rollback --yes # --yes confirms the destructive restore
ocp doctor
If ocp doctor still reports problems after rollback, open a GitHub issue
with the snapshot path and the doctor JSON output (ocp doctor --json).
OpenClaw Auto-Sync (v3.11.0+)
Whenever the model list in models.json changes, ocp update automatically reconciles your OpenClaw config so the model dropdown stays in sync — no more "I upgraded OCP but my Telegram bot still shows the old models" surprises.
What gets synced (and only this — all other config keys are preserved):
models.providers."claude-local".modelsin~/.openclaw/openclaw.jsonagents.defaults.models["claude-local/*"]aliases
Safety:
- Timestamped backup written before every change:
~/.openclaw/openclaw.json.bak.<ms> - Idempotent — already-in-sync runs are a no-op (no backup, no rewrite)
- Non-fatal — sync failure does NOT abort
ocp update;/v1/modelsstill works - Skips silently if OpenClaw is not installed (
~/.openclaw/openclaw.jsonmissing)
Manual trigger (e.g. after fixing a hand-edited config, or for the one-time v3.10.0→v3.11.0 bootstrap quirk):
node ~/ocp/scripts/sync-openclaw.mjs
node ~/ocp/scripts/sync-openclaw.mjs --quiet # silent unless changes
Opt-out: ocp update only invokes the sync if node and scripts/sync-openclaw.mjs are both present. Removing the script disables auto-sync; the rest of ocp update still works.
One-time bootstrap caveat (v3.10.0 → v3.11.0 only): the first ocp update to v3.11.0 runs the old cmd_update already loaded into your shell, so the new sync hook does NOT fire on this single jump. Run node ~/ocp/scripts/sync-openclaw.mjs once manually. Every future update from v3.11.0+ syncs automatically. (Also captured in the README Troubleshooting section as a bootstrap quirk.)
Other IDEs (Cline / Aider / Cursor / opencode) query /v1/models live, so they pick up new models on the next request — no sync needed. Continue.dev users edit their own config.json model id manually.