[{"data":1,"prerenderedAt":3080},["ShallowReactive",2],{"blog-post-openclaw-latest-version":3,"related-posts-openclaw-latest-version":493},{"id":4,"title":5,"author":6,"body":11,"category":465,"date":466,"description":467,"extension":468,"featured":469,"hideToc":469,"image":470,"imageAlt":471,"imageHeight":472,"imageWidth":473,"lang":474,"meta":475,"navigation":476,"noindex":469,"path":477,"readingTime":478,"redirected":469,"relatedSlugs":479,"seo":482,"seoTitle":483,"stem":484,"tags":485,"updatedDate":474,"__hash__":492},"blog/blog/openclaw-latest-version.md","OpenClaw Latest Version: What It Is and How to Update (2026)",{"name":7,"role":8,"avatar":9,"url":10},"Shabnam Katoch","Growth Head","/img/avatars/shabnam-profile.jpeg","https://www.betterclaw.io/about",{"type":12,"value":13,"toc":454},"minimark",[14,27,32,39,42,96,99,103,126,129,158,161,165,168,193,196,199,206,210,222,225,239,242,267,270,277,281,286,292,297,300,304,307,310,313,319,325,329,332,345,355,361,374,378,381,395,399,403,409,414,426,431,434,439,442,447,450],[15,16,17,18,22,23,26],"p",{},"Current stable release: ",[19,20,21],"strong",{},"2026.9.6",", published 23 September 2026. Extended stable (the LTS line): ",[19,24,25],{},"2026.7.35",". Here's what's in the latest version, how to check what you're running, and how to update without breaking a working setup.",[28,29,31],"h2",{"id":30},"what-is-the-latest-version-of-openclaw","What is the latest version of OpenClaw?",[15,33,34,35,38],{},"2026.9.6, published on 23 September 2026 and marked ",[19,36,37],{},"Latest"," on the project's release page.",[15,40,41],{},"One thing to know if you're on macOS: the original 2026.9.6 macOS build crashed at launch, and it was replaced on 24 September at 09:52 UTC with a rebuilt, notarized build carrying the fix. If you installed the earlier build and the app won't open, install the DMG once more. The npm package was never affected.",[43,44,45,61],"table",{},[46,47,48],"thead",{},[49,50,51,55,58],"tr",{},[52,53,54],"th",{},"Channel",[52,56,57],{},"Version",[52,59,60],{},"Who it's for",[62,63,64,75,85],"tbody",{},[49,65,66,70,72],{},[67,68,69],"td",{},"Stable",[67,71,21],{},[67,73,74],{},"Most people",[49,76,77,80,82],{},[67,78,79],{},"Extended stable (LTS)",[67,81,25],{},[67,83,84],{},"Servers and teams that value quiet over new",[49,86,87,90,93],{},[67,88,89],{},"Beta",[67,91,92],{},"Published ahead of stable",[67,94,95],{},"Testing and early feedback",[15,97,98],{},"Quick note on the LTS line, because the numbering confuses people: 2026.7.33 and 2026.7.34 were unstable and were never published as GitHub releases, so 2026.7.35 is the first proper release on the July maintenance line and carries their changelogs too. If you're on extended stable and skipped those, 2026.7.35 is where you should be.",[28,100,102],{"id":101},"how-to-check-which-version-youre-running","How to check which version you're running",[104,105,110],"pre",{"className":106,"code":107,"language":108,"meta":109,"style":109},"language-bash shiki shiki-themes github-light","openclaw --version\n","bash","",[111,112,113],"code",{"__ignoreMap":109},[114,115,118,122],"span",{"class":116,"line":117},"line",1,[114,119,121],{"class":120},"s7eDp","openclaw",[114,123,125],{"class":124},"sYu0t"," --version\n",[15,127,128],{},"If the Gateway is running but you want its full picture, including whether an update is waiting:",[104,130,132],{"className":106,"code":131,"language":108,"meta":109,"style":109},"openclaw status --all\nopenclaw update status --json\n",[111,133,134,145],{"__ignoreMap":109},[114,135,136,138,142],{"class":116,"line":117},[114,137,121],{"class":120},[114,139,141],{"class":140},"sYBdl"," status",[114,143,144],{"class":124}," --all\n",[114,146,148,150,153,155],{"class":116,"line":147},2,[114,149,121],{"class":120},[114,151,152],{"class":140}," update",[114,154,141],{"class":140},[114,156,157],{"class":124}," --json\n",[15,159,160],{},"Compare the result with 2026.9.6 above. Don't trust a version number you remember installing, because automatic updates may have moved you.",[28,162,164],{"id":163},"whats-new-in-202696","What's new in 2026.9.6",[15,166,167],{},"Straight from the project's release notes, this release focuses on managed updates, recovery and reporting rather than headline features:",[169,170,171,175,178,181,184,187,190],"ul",{},[172,173,174],"li",{},"Clearer outcomes when a managed update runs, so you know whether it succeeded, failed or was deliberately skipped.",[172,176,177],{},"Recovery for unfinished work after a restart, so queued and in-flight work isn't silently lost.",[172,179,180],{},"Complete 30-day usage reporting across the full session report.",[172,182,183],{},"A GitHub reader that puts public discussions and diffs beside your chat.",[172,185,186],{},"Remote workspaces gain Files, Memory and Skills.",[172,188,189],{},"Meeting notes that update while capture is still running.",[172,191,192],{},"New chat-model support for Claude Opus 5.5, GPT-6 Sol and Luna, and Grok 4.7.",[15,194,195],{},"Two practical fixes worth calling out. The Windows installer can now continue after a failed Node package-manager attempt, falling back to downloading an official portable runtime into your user account with no administrator access required. And production npm installs are about 18 MiB smaller, with no configuration change needed.",[15,197,198],{},"Release scale: 2,614 pull requests, 178 direct commits, around 350 contributors.",[15,200,201],{},[202,203],"img",{"alt":204,"src":205},"Two lanes, different speeds: stable ships 2026.9.1 to 2026.9.6 every few days, extended stable sits at 2026.7.35","/img/blog/openclaw-latest-version-release-lines.jpg",[28,207,209],{"id":208},"how-to-update-openclaw","How to update OpenClaw",[104,211,213],{"className":106,"code":212,"language":108,"meta":109,"style":109},"openclaw update\n",[111,214,215],{"__ignoreMap":109},[114,216,217,219],{"class":116,"line":117},[114,218,121],{"class":120},[114,220,221],{"class":140}," update\n",[15,223,224],{},"Before you run it, do three things. Take a backup, because an update that goes wrong at 2am is much easier to undo with one. Note the version you're on now, so you know what to roll back to. And read the release notes for the versions you're skipping, since defaults sometimes change between releases.",[15,226,227,228,233,234,238],{},"That last point matters more than it sounds. The 2026.9.2 release turned on Swarm sub-agents by default and opened cross-agent session visibility by default, which changes what your agents can see and do without you editing a single config line. We wrote that release up in the ",[229,230,232],"a",{"href":231},"/blog/openclaw-2026-9-2-update","2026.9.2 breakdown",", and the full procedure, including rollback, is in ",[229,235,237],{"href":236},"/blog/how-to-update-openclaw","how to update OpenClaw",".",[15,240,241],{},"After updating:",[104,243,245],{"className":106,"code":244,"language":108,"meta":109,"style":109},"openclaw doctor --fix\nopenclaw gateway restart\n",[111,246,247,257],{"__ignoreMap":109},[114,248,249,251,254],{"class":116,"line":117},[114,250,121],{"class":120},[114,252,253],{"class":140}," doctor",[114,255,256],{"class":124}," --fix\n",[114,258,259,261,264],{"class":116,"line":147},[114,260,121],{"class":120},[114,262,263],{"class":140}," gateway",[114,265,266],{"class":140}," restart\n",[15,268,269],{},"Doctor migrates configuration that moved between versions and repairs common breakage. Run it before you start debugging anything by hand.",[15,271,272,273,276],{},"An update that prints \"success\" has only proven that the package installed. Whether your config still validates and the Gateway came back are separate questions, and ",[111,274,275],{},"openclaw doctor --fix"," answers both.",[28,278,280],{"id":279},"which-release-channel-should-you-be-on","Which release channel should you be on?",[15,282,283,285],{},[19,284,69],{}," is right for most people. You get fixes quickly and the cadence is fast enough that bugs rarely live long.",[15,287,288,291],{},[19,289,290],{},"Extended stable"," is for anyone running OpenClaw as infrastructure: a server, a team Gateway, anything where an unexpected behaviour change costs more than a missing feature. It's a maintenance line that receives security and reliability backports rather than new features. The trade is that you're deliberately months behind on capability.",[15,293,294,296],{},[19,295,89],{}," exists if you want to help catch problems before they reach stable. Don't run it on the Gateway your business depends on.",[15,298,299],{},"The honest framing: the project ships fast, and that's a feature and a cost at the same time. In September alone there were six stable releases. If reading a changelog every few days isn't something you have time for, extended stable is the channel that respects that.",[28,301,303],{"id":302},"openclaw-20-and-where-it-sits","OpenClaw 2.0, and where it sits",[15,305,306],{},"People search for \"OpenClaw 2.0\" expecting it to be the latest version. It isn't, quite.",[15,308,309],{},"OpenClaw 2.0 is the marketing name for v2026.8.1, released at the end of August 2026 and listed in the docs as \"v2026.8.1 (AKA OpenClaw 2.0)\". It was the big one: a rebuilt web experience, much simpler onboarding that detects existing AI subscriptions and local models, stronger memory and session continuity, shared sessions, and automatic skill learning through Skill Workshop. It pulled in work from 933 developers across more than 16,000 pull requests.",[15,311,312],{},"Everything since, the 8.2 and 9.x releases, builds on that. So 2.0 is the current generation, and 2026.9.6 is the current version of it.",[15,314,315],{},[202,316],{"alt":317,"src":318},"Five steps in this order: back up, note your version, openclaw update, doctor --fix, gateway restart","/img/blog/openclaw-latest-version-update-steps.jpg",[15,320,321],{},[202,322],{"alt":323,"src":324},"Three things that go wrong after updating: Gateway will not start, settings look reset, agent behaves differently","/img/blog/openclaw-latest-version-what-goes-wrong.jpg",[28,326,328],{"id":327},"if-the-update-breaks-something","If the update breaks something",[15,330,331],{},"The most common outcomes, in rough order of frequency:",[15,333,334,337,338,340,341,344],{},[19,335,336],{},"The Gateway won't start."," Run ",[111,339,275],{},", then ",[111,342,343],{},"openclaw gateway restart",". If it still won't come up, the cause is usually an incomplete install, a config key that moved, or a supervisor entry pointing at the old install.",[15,346,347,350,351,354],{},[19,348,349],{},"Settings or skills look reset."," Newer releases preserve these through automatic updates, so if something is missing, check that the update actually completed with ",[111,352,353],{},"openclaw update status --json"," rather than assuming it wiped your setup.",[15,356,357,360],{},[19,358,359],{},"An agent behaves differently."," Check the release notes for changed defaults before you go looking for a bug in your own config. Swarm and session visibility are the two recent examples.",[15,362,363,364,368,369,373],{},"Our ",[229,365,367],{"href":366},"/blog/openclaw-security-checklist","OpenClaw security checklist"," is worth a pass after any update that changes defaults, and if you want to understand what the Gateway is actually doing underneath all this, ",[229,370,372],{"href":371},"/blog/openclaw-gateway-guide","how OpenClaw works"," covers the architecture.",[28,375,377],{"id":376},"do-you-need-to-update-every-time","Do you need to update every time?",[15,379,380],{},"No, and chasing every release is a reasonable thing to opt out of. Update promptly for security fixes, update deliberately for features, and consider extended stable if the answer to \"did anything change in this release?\" is a question you don't want to ask every few days.",[15,382,383,384,390,391,238],{},"That cadence is exactly why managed hosting exists as a category. On BetterClaw, updates are staged and applied for you, so there's no changelog to read and no 2am Gateway that won't start. Plans start at $19 a month with your own model keys. ",[229,385,389],{"href":386,"rel":387},"https://app.betterclaw.io/sign-in",[388],"nofollow","Get started"," or ",[229,392,394],{"href":393},"/pricing","see the full pricing",[28,396,398],{"id":397},"frequently-asked-questions","Frequently Asked Questions",[15,400,401],{},[19,402,31],{},[15,404,405,406,238],{},"OpenClaw 2026.9.6, published on 23 September 2026, is the current stable release. The extended stable (LTS) line sits at 2026.7.35. On macOS, make sure you have the rebuilt 2026.9.6 build from 24 September, since the original build crashed at launch. Check your own version with ",[111,407,408],{},"openclaw --version",[15,410,411],{},[19,412,413],{},"How do I update OpenClaw to the latest version?",[15,415,416,417,340,420,422,423,425],{},"Run ",[111,418,419],{},"openclaw update",[111,421,275],{}," and ",[111,424,343],{},". Before updating, take a backup and note your current version so a rollback is straightforward. Read the notes for any releases you're skipping, because defaults occasionally change between versions.",[15,427,428],{},[19,429,430],{},"Is OpenClaw 2.0 the same as the latest version?",[15,432,433],{},"Not exactly. OpenClaw 2.0 is the name for v2026.8.1, released at the end of August 2026, which brought the rebuilt web experience, simpler onboarding and stronger memory. Every release since, including 2026.9.6, builds on it. So you're on the 2.0 generation, and 2026.9.6 is its current version.",[15,435,436],{},[19,437,438],{},"How often does OpenClaw release updates?",[15,440,441],{},"Every few days on the stable channel. September 2026 alone saw six stable releases, from 2026.9.1 through 2026.9.6, and individual releases routinely carry over a thousand pull requests. The extended stable line moves far more slowly and only receives security and reliability backports.",[15,443,444],{},[19,445,446],{},"Should I use stable or extended stable?",[15,448,449],{},"Use stable if OpenClaw is a personal tool and you want fixes quickly. Use extended stable if it's infrastructure, since a maintenance line that changes rarely is worth more than new features when other people depend on the Gateway. Extended stable is currently 2026.7.35, which is the first published release on the July line after two unstable builds that were never released.",[451,452,453],"style",{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}",{"title":109,"searchDepth":147,"depth":147,"links":455},[456,457,458,459,460,461,462,463,464],{"id":30,"depth":147,"text":31},{"id":101,"depth":147,"text":102},{"id":163,"depth":147,"text":164},{"id":208,"depth":147,"text":209},{"id":279,"depth":147,"text":280},{"id":302,"depth":147,"text":303},{"id":327,"depth":147,"text":328},{"id":376,"depth":147,"text":377},{"id":397,"depth":147,"text":398},"Guides","2026-09-29","OpenClaw 2026.9.6 is the current release. What changed, how to check your version, how to update safely, and which channel you should be on.","md",false,"/img/blog/openclaw-latest-version.jpg","OpenClaw latest version: openclaw --version shows 2026.9.6",512,1024,null,{},true,"/blog/openclaw-latest-version","7 min read",[208,480,481],"openclaw-gateway-wont-start-after-update","openclaw-backup-restore-before-update",{"title":5,"description":467},"OpenClaw Latest Version 2026.9.6: What Changed + Update","blog/openclaw-latest-version",[486,487,419,488,489,490,491],"openclaw latest version","openclaw 2026.9.6","openclaw release notes","openclaw version check","openclaw extended stable","openclaw 2.0","eJRcQunx0a8LPseFN_gbyhxlsL-2VPQ6G7DV8m7Nmh8",[494,1035,1660],{"id":495,"title":496,"author":497,"body":498,"category":1017,"date":1018,"description":1019,"extension":468,"featured":469,"hideToc":469,"image":1020,"imageAlt":474,"imageHeight":474,"imageWidth":474,"lang":474,"meta":1021,"navigation":476,"noindex":469,"path":236,"readingTime":1022,"redirected":469,"relatedSlugs":474,"seo":1023,"seoTitle":1024,"stem":1025,"tags":1026,"updatedDate":1033,"__hash__":1034},"blog/blog/how-to-update-openclaw.md","How to Update OpenClaw Without Breaking Your Setup",{"name":7,"role":8,"avatar":9},{"type":12,"value":499,"toc":995},[500,506,509,512,515,518,522,525,528,531,534,537,545,549,552,557,572,576,582,586,589,593,596,606,612,616,619,633,637,640,643,649,652,657,670,684,712,726,729,733,736,742,753,759,765,772,776,779,783,786,792,796,799,814,818,821,826,834,838,841,844,847,850,853,856,862,866,869,872,875,881,889,892,900,902,906,916,921,924,929,932,937,940,945,948,952,992],[15,501,502],{},[503,504,505],"em",{},"Last time you updated, your cron jobs vanished. This time, you'll back up first, update safely, and know exactly how to roll back if anything goes wrong.",[15,507,508],{},"I updated OpenClaw on a Tuesday afternoon. By Tuesday evening, my customer support agent had stopped responding on Telegram, three cron jobs had silently deactivated, and my gateway was binding to a different port than before.",[15,510,511],{},"The update itself took 30 seconds. The debugging took four hours. The worst part: I could have prevented all of it with a 5-minute backup before hitting the update command.",[15,513,514],{},"OpenClaw releases multiple updates per week. Some are minor fixes. Some change config behavior without clear documentation. With 7,900+ open issues on GitHub and the project transitioning to an open-source foundation after Peter Steinberger's move to OpenAI, the pace of change is high and the communication about breaking changes is inconsistent.",[15,516,517],{},"Here's how to update OpenClaw safely every time. Bookmark this page. You'll need it again.",[28,519,521],{"id":520},"check-your-current-version-first","Check your current version first",[15,523,524],{},"Before you update anything, know what version you're running right now. This matters for two reasons.",[15,526,527],{},"First, if something breaks after the update, you need to know which version to roll back to. If you don't know your current version, you can't roll back precisely. You're guessing.",[15,529,530],{},"Second, the changelog between your current version and the latest version tells you what changed. If a breaking change happened between your version and the new one, you'll know before you update instead of discovering it through broken behavior.",[15,532,533],{},"Run the version check command in your terminal. OpenClaw will report its current version number. Write it down or screenshot it. You'll need this if rollback becomes necessary.",[15,535,536],{},"Also check which version is the latest available. Compare the two. If you're one version behind, the risk is low. If you're ten versions behind, read the changelogs for each version in between. Multiple small breaking changes stack up.",[15,538,539,540,544],{},"For the ",[229,541,543],{"href":542},"/blog/openclaw-setup-guide-complete","complete OpenClaw setup sequence and where updates fit",", our setup guide covers the full installation and configuration flow.",[28,546,548],{"id":547},"back-up-these-four-things-before-you-update","Back up these four things before you update",[15,550,551],{},"This takes 5 minutes. It saves hours of debugging if something goes wrong.",[553,554,556],"h3",{"id":555},"your-personality-and-memory-files","Your personality and memory files",[15,558,559,560,563,564,567,568,571],{},"Copy your ",[111,561,562],{},"SOUL.md",", ",[111,565,566],{},"MEMORY.md",", and ",[111,569,570],{},"USER.md"," (if it exists) to a safe location outside the OpenClaw directory. These files define your agent's personality, accumulated knowledge, and user preferences. They're the files you've spent the most time crafting. Losing them means recreating your agent's personality from scratch.",[553,573,575],{"id":574},"your-config-file","Your config file",[15,577,559,578,581],{},[111,579,580],{},"openclaw.json"," (or wherever your configuration lives) to the same backup location. This file contains your model providers, API credentials, channel connections, gateway settings, and every customization you've made. If the update changes config key names or structure, you'll need the original to compare and migrate.",[553,583,585],{"id":584},"your-installed-skills-list","Your installed skills list",[15,587,588],{},"Note which skills you have installed and where they came from. After an update, skills can go inactive or need reinstallation. If you don't know which skills you had, you won't notice they're missing until the agent fails to perform a task it used to handle fine.",[553,590,592],{"id":591},"your-cron-jobs-and-scheduled-tasks","Your cron jobs and scheduled tasks",[15,594,595],{},"Export or write down anything running on a schedule: morning briefings, hourly checks, heartbeat automations. Scheduled jobs are the easiest thing to lose track of, because a missing one fails silently. Nothing errors, the agent simply stops doing something it used to do, and you notice a week later when you realise the briefing stopped arriving.",[15,597,598,599,563,601,563,603,605],{},"The 5-minute backup rule: copy ",[111,600,562],{},[111,602,566],{},[111,604,570],{},", and your config file to a separate folder before every update. This single habit prevents 90% of update disasters.",[15,607,608],{},[202,609],{"alt":610,"src":611},"OpenClaw update backup checklist showing SOUL.md, MEMORY.md, USER.md, and config file in a safe location","/img/blog/how-to-update-openclaw-backup.jpg",[553,613,615],{"id":614},"what-changed-about-backups-in-202692","What changed about backups in 2026.9.2",[15,617,618],{},"Two things worth knowing if you are on 2026.9.2 or later. Backup integrity got stricter: corrupt archive headers are now rejected outright rather than accepted as a partial backup, and Skill Workshop backups refuse incomplete directory snapshots. That is the right behaviour, but it means a backup that used to appear to work may now fail loudly instead. Better to find that out before you need it.",[15,620,621,622,625,626,630,631,238],{},"Restoring also needs free temporary disk space, because the restore prepares a safe copy first and fails if it cannot. If you are restoring onto a nearly full disk, clear space before you start rather than halfway through. The built-in ",[111,623,624],{},"openclaw backup create"," command, and the two-step restore it pairs with, are covered in ",[229,627,629],{"href":628},"/blog/openclaw-backup-restore-before-update","how to back up and restore an OpenClaw agent",". The rest of that release, including two defaults that changed, is in our ",[229,632,232],{"href":231},[28,634,636],{"id":635},"the-actual-update-process","The actual update process",[15,638,639],{},"Once you've backed up, the update itself is straightforward.",[15,641,642],{},"Run the npm global update command for OpenClaw. This pulls the latest version and replaces the OpenClaw binary. The process typically takes 30-60 seconds depending on your internet speed.",[15,644,645,648],{},[19,646,647],{},"What \"success\" looks like:"," The terminal shows the new version number with no error messages. If you see warnings about deprecated dependencies, those are usually harmless. If you see actual errors (permission denied, EACCES, npm ERR!), the update didn't complete and you're still on the old version.",[15,650,651],{},"After the update completes, restart your gateway. The new version only takes effect after a gateway restart. If you update but don't restart, you're running the old code with the new binary sitting idle.",[15,653,654],{},[19,655,656],{},"Two flags worth knowing as of the 2026.9 releases.",[15,658,659,662,663,666,667,669],{},[111,660,661],{},"openclaw update --no-restart"," skips the automatic Gateway restart after a successful update. Use it only when you have already stopped the Gateway yourself, and restart it manually afterwards. Otherwise you get the idle-binary problem described above, just with extra steps. There is one specific case where it is the documented path rather than an option: if you are on ",[111,664,665],{},"2026.8.2"," on a machine with no service manager (common on bare Linux installs), run ",[111,668,661],{}," once to get past it.",[104,671,673],{"className":106,"code":672,"language":108,"meta":109,"style":109},"openclaw update --no-restart\n",[111,674,675],{"__ignoreMap":109},[114,676,677,679,681],{"class":116,"line":117},[114,678,121],{"class":120},[114,680,152],{"class":140},[114,682,683],{"class":124}," --no-restart\n",[15,685,686,689,690,693,694,697,698,563,701,563,704,707,708,711],{},[111,687,688],{},"openclaw update status"," reports where your install actually sits without changing anything. On extended-stable package installs it runs the same public-selector and exact-package verification the foreground update does, and it will tell you when your installed version is ",[503,691,692],{},"ahead"," of extended-stable rather than behind. When it fails it returns a ",[111,695,696],{},"registry.reason"," in its JSON (",[111,699,700],{},"selector_missing",[111,702,703],{},"selector_query_failed",[111,705,706],{},"exact_package_mismatch",", or ",[111,709,710],{},"unsupported_git_channel","), which is usually faster to act on than the update command's own output.",[104,713,715],{"className":106,"code":714,"language":108,"meta":109,"style":109},"openclaw update status\n",[111,716,717],{"__ignoreMap":109},[114,718,719,721,723],{"class":116,"line":117},[114,720,121],{"class":120},[114,722,152],{"class":140},[114,724,725],{"class":140}," status\n",[15,727,728],{},"The 2026.9 line also made the update itself considerably safer to run: a failed post-update Doctor check now rolls the npm candidate back, config and secret references survive a failed upgrade, failures are handed to a built-in triage agent, and the updater waits for plugin readiness before restarting. If you have been holding off on updating because a previous one stranded you, that is the change that matters.",[28,730,732],{"id":731},"what-to-check-immediately-after-updating","What to check immediately after updating",[15,734,735],{},"Don't assume the update worked just because the terminal didn't show errors. Check three things within the first 5 minutes.",[15,737,738,741],{},[19,739,740],{},"Is your agent responding?"," Send a test message through your primary channel (Telegram, WhatsApp, whatever you use). If the agent responds normally, the core system is working.",[15,743,744,747,748,422,750,752],{},[19,745,746],{},"Are your memory files intact?"," Check that ",[111,749,562],{},[111,751,566],{}," are still present and contain the expected content. Some updates have been reported to reset or modify these files. If they've changed, restore from your backup.",[15,754,755,758],{},[19,756,757],{},"Are your skills still installed and active?"," Ask your agent to perform a task that requires a specific skill (web search, file operation, calendar check). If the skill fails, it may have been deactivated by the update. Reinstall it.",[15,760,761,764],{},[19,762,763],{},"Are your cron jobs still running?"," This is the one people miss. Cron jobs can silently deactivate after updates. Check your cron configuration and verify the schedules are still active. If your morning briefing doesn't arrive tomorrow, this is probably why.",[15,766,539,767,771],{},[229,768,770],{"href":769},"/blog/openclaw-best-practices","seven practices every stable OpenClaw setup should follow",", our best practices guide covers ongoing maintenance including update hygiene.",[28,773,775],{"id":774},"what-commonly-breaks-between-versions-and-the-quick-fix","What commonly breaks between versions (and the quick fix)",[15,777,778],{},"Three things break more often than everything else combined.",[553,780,782],{"id":781},"config-key-renames","Config key renames",[15,784,785],{},"OpenClaw occasionally renames config keys between versions. A field that was called one thing in the old version might have a slightly different name in the new version. When this happens, the gateway either ignores the old key (silently dropping your setting) or throws a validation error.",[15,787,788,791],{},[19,789,790],{},"Quick fix:"," Compare your backed-up config file with the default config for the new version. Look for keys that exist in your backup but not in the new default. They've probably been renamed. Update the key names and restart.",[553,793,795],{"id":794},"skills-going-inactive","Skills going inactive",[15,797,798],{},"Updates can change how skills are loaded or validated. A skill that worked in the previous version might fail validation in the new one due to changed schema requirements, missing fields, or updated security checks.",[15,800,801,803,804,808,809,813],{},[19,802,790],{}," Reinstall the affected skills. If reinstallation fails, check if the skill has been updated on ClawHub to match the new OpenClaw version. If not, the skill may need an update from its maintainer. For the ",[229,805,807],{"href":806},"/blog/openclaw-skills-install-guide","skill vetting and installation guide",", our ",[229,810,812],{"href":811},"/blog/best-openclaw-skills","skills post"," covers the safe installation process.",[553,815,817],{"id":816},"gateway-binding-changes","Gateway binding changes",[15,819,820],{},"Some updates change the default gateway binding behavior. If your gateway was bound to a specific port or address, an update might reset it to the default. This breaks channel connections and API access.",[15,822,823,825],{},[19,824,790],{}," Check your gateway config after updating. Verify the bind address and port match what you had before. Restore from your backup if they've changed.",[15,827,828,829,833],{},"If managing updates, config migrations, and skill compatibility sounds like more maintenance than you want, ",[229,830,832],{"href":831},"/","BetterClaw handles updates automatically",". Your config is preserved. Your skills stay active. Your memory files are intact. $49/month for Pro, BYOK. You never touch any of this.",[28,835,837],{"id":836},"how-to-roll-back-if-something-goes-wrong","How to roll back if something goes wrong",[15,839,840],{},"This is the section you'll bookmark.",[15,842,843],{},"If the update broke something and you can't fix it quickly, rolling back to the previous version is the fastest path to a working agent.",[15,845,846],{},"Install the specific previous version of OpenClaw by specifying the exact version number in the npm install command. Use the version number you wrote down before the update. This replaces the new version with the old one.",[15,848,849],{},"After installing the old version, restore your backed-up config file and memory files. Restart the gateway. Your agent should be back to its pre-update state.",[15,851,852],{},"The rollback takes about 2 minutes if you have your backup. It takes much longer if you don't, because you'll be trying to recreate settings from memory. This is why the backup step isn't optional.",[15,854,855],{},"Rolling back is not failure. It's the smart response when an update introduces problems you can't fix immediately. Update again later when the community has identified and resolved the breaking changes.",[15,857,858],{},[202,859],{"alt":860,"src":861},"OpenClaw rollback process showing version pinning, config restore, and gateway restart steps","/img/blog/how-to-update-openclaw-rollback.jpg",[28,863,865],{"id":864},"the-update-schedule-that-actually-works","The update schedule that actually works",[15,867,868],{},"Here's what nobody tells you about updating OpenClaw: you don't need to update every time a new version drops.",[15,870,871],{},"OpenClaw releases multiple times per week. Most updates are minor. Unless the changelog specifically mentions a security fix (like the CVE-2026-25253 patch for the CVSS 8.8 vulnerability) or a feature you need, waiting a few days lets the community find breaking changes first.",[15,873,874],{},"Check the GitHub issues and Discord after a new release. If people report problems, wait for the fix. If the community is quiet, the update is probably safe.",[15,876,877,880],{},[19,878,879],{},"Security updates are the exception."," When a CVE is published, update immediately. The one-click RCE vulnerability (CVE-2026-25253) demonstrated why: 30,000+ instances were found exposed without authentication. Delaying security patches creates real risk.",[15,882,883,884,888],{},"The ",[229,885,887],{"href":886},"/compare/openclaw","managed vs self-hosted comparison"," covers how updates are handled across different deployment approaches, including which platforms apply security patches automatically.",[15,890,891],{},"For everything else, update weekly or biweekly. Back up first. Check after. Roll back if needed. That's the whole process.",[15,893,894,895,899],{},"If you'd rather never think about updates again, ",[229,896,898],{"href":386,"rel":897},[388],"give Better Claw a try",". $49/month for Pro, BYOK with 28+ providers. Updates are automatic. Config is preserved. Security patches land same-day. Your agent stays current while you focus on what it does, not how it runs.",[28,901,398],{"id":397},[15,903,904],{},[19,905,413],{},[15,907,908,909,563,911,563,913,915],{},"Run the npm global update command for OpenClaw in your terminal. Before updating, back up your ",[111,910,562],{},[111,912,566],{},[111,914,570],{},", and config file. After updating, restart the gateway and verify your agent is responding, memory files are intact, skills are active, and cron jobs are running. The update takes about 30-60 seconds. The backup and verification add 10 minutes of safety.",[15,917,918],{},[19,919,920],{},"What breaks when I update OpenClaw?",[15,922,923],{},"The three most common issues are: config key renames (your settings silently stop working), skills going inactive (changed validation requirements), and gateway binding changes (connection settings reset to defaults). All three are fixable by comparing your backed-up config with the new defaults and restoring any changed values. The backup before updating is what makes these fixable instead of catastrophic.",[15,925,926],{},[19,927,928],{},"How do I roll back an OpenClaw update?",[15,930,931],{},"Install the previous version by specifying the exact version number in the npm install command. Restore your backed-up config file and memory files. Restart the gateway. The rollback takes about 2 minutes if you have your backup ready. This is why writing down your current version before updating is essential. Without it, you're guessing which version to roll back to.",[15,933,934],{},[19,935,936],{},"How often should I update OpenClaw?",[15,938,939],{},"For most users, weekly or biweekly updates are sufficient. Wait a day or two after each release to let the community identify breaking changes. The exception is security updates: when a CVE is published (like CVE-2026-25253, a CVSS 8.8 vulnerability), update immediately. On managed platforms like BetterClaw, updates are applied automatically with config preservation, so you never need to manage this manually.",[15,941,942],{},[19,943,944],{},"Is it safe to skip OpenClaw updates?",[15,946,947],{},"Skipping non-security updates for a few weeks is generally fine. Skipping security updates is risky. With 30,000+ exposed instances found without authentication and the ClawHavoc campaign targeting 824+ malicious skills, running outdated versions increases your exposure. The safest approach: apply security patches immediately, delay feature updates by a few days to let the community test them first.",[28,949,951],{"id":950},"related-reading","Related Reading",[169,953,954,961,967,973,979,986],{},[172,955,956,960],{},[229,957,959],{"href":958},"/blog/openclaw-gateway-wont-start-after-update","OpenClaw Gateway Won't Start After Updating"," — Ten post-update failures, each matched to the log line it prints",[172,962,963,966],{},[229,964,965],{"href":542},"OpenClaw Setup Guide: Complete Walkthrough"," — Full installation and configuration flow",[172,968,969,972],{},[229,970,971],{"href":769},"OpenClaw Best Practices"," — Seven practices for ongoing maintenance and stability",[172,974,975,978],{},[229,976,977],{"href":811},"Best OpenClaw Skills (Tested & Vetted)"," — Safe skill installation after an update breaks them",[172,980,981,985],{},[229,982,984],{"href":983},"/blog/openclaw-security-2026","OpenClaw Security Risks Explained"," — Why security patches can't be delayed",[172,987,988,991],{},[229,989,990],{"href":886},"BetterClaw vs Self-Hosted OpenClaw"," — How updates are handled across deployment approaches",[451,993,994],{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":109,"searchDepth":147,"depth":147,"links":996},[997,998,1006,1007,1008,1013,1014,1015,1016],{"id":520,"depth":147,"text":521},{"id":547,"depth":147,"text":548,"children":999},[1000,1002,1003,1004,1005],{"id":555,"depth":1001,"text":556},3,{"id":574,"depth":1001,"text":575},{"id":584,"depth":1001,"text":585},{"id":591,"depth":1001,"text":592},{"id":614,"depth":1001,"text":615},{"id":635,"depth":147,"text":636},{"id":731,"depth":147,"text":732},{"id":774,"depth":147,"text":775,"children":1009},[1010,1011,1012],{"id":781,"depth":1001,"text":782},{"id":794,"depth":1001,"text":795},{"id":816,"depth":1001,"text":817},{"id":836,"depth":147,"text":837},{"id":864,"depth":147,"text":865},{"id":397,"depth":147,"text":398},{"id":950,"depth":147,"text":951},"Best Practices","2026-04-06","Back up 3 files, run the update, check 4 things after. If it breaks, roll back in 2 minutes. Here's the safe OpenClaw update process.","/img/blog/how-to-update-openclaw.jpg",{},"10 min read",{"title":496,"description":1019},"How to Update OpenClaw Without Breaking Anything","blog/how-to-update-openclaw",[237,1027,1028,1029,1030,1031,1032],"OpenClaw update guide","update OpenClaw safely","OpenClaw breaking changes","OpenClaw rollback","OpenClaw new version","OpenClaw upgrade 2026","2026-09-07","lwUR69qNmBkBca7ATbZvfk9U9raHGs7jquy5S1IewBQ",{"id":1036,"title":1037,"author":1038,"body":1039,"category":465,"date":1643,"description":1644,"extension":468,"featured":469,"hideToc":469,"image":1645,"imageAlt":474,"imageHeight":472,"imageWidth":473,"lang":474,"meta":1646,"navigation":476,"noindex":469,"path":628,"readingTime":478,"redirected":469,"relatedSlugs":474,"seo":1647,"seoTitle":1648,"stem":1649,"tags":1650,"updatedDate":1643,"__hash__":1659},"blog/blog/openclaw-backup-restore-before-update.md","How to Back Up and Restore an OpenClaw Agent Before Updating",{"name":7,"role":8,"avatar":9},{"type":12,"value":1040,"toc":1625},[1041,1044,1047,1050,1054,1061,1162,1171,1190,1197,1201,1204,1228,1238,1257,1264,1267,1277,1281,1284,1288,1327,1330,1333,1337,1368,1371,1382,1388,1392,1399,1444,1455,1461,1467,1471,1517,1527,1531,1537,1547,1553,1555,1559,1576,1580,1588,1592,1605,1609,1615,1619,1622],[15,1042,1043],{},"Updates break things. A backup that takes thirty seconds to make can save hours of rebuilding. Here's the one command that does it properly, what it captures, and how to get back if the update goes wrong.",[15,1045,1046],{},"The most upvoted comment in every \"update broke my agent\" thread this year says the same thing: I stop OpenClaw and back up first now. Learned the hard way, every time.",[15,1048,1049],{},"The good news is that OpenClaw ships a backup command that does this correctly, and most people don't know it exists. The bad news is that the way most people back up by hand (copying the folder while the Gateway is running) can produce an archive that doesn't restore. Here's the right way, short.",[28,1051,1053],{"id":1052},"what-actually-needs-backing-up","What actually needs backing up",[15,1055,1056,1057,1060],{},"Everything lives under the state directory, ",[111,1058,1059],{},"~/.openclaw"," by default, plus your agent workspace. The pieces that matter:",[43,1062,1063,1076],{},[46,1064,1065],{},[49,1066,1067,1070,1073],{},[52,1068,1069],{},"What",[52,1071,1072],{},"Where",[52,1074,1075],{},"Why it matters",[62,1077,1078,1090,1103,1116,1129,1151],{},[49,1079,1080,1083,1087],{},[67,1081,1082],{},"Config",[67,1084,1085],{},[111,1086,580],{},[67,1088,1089],{},"Gateway settings, channels, model choices",[49,1091,1092,1095,1100],{},[67,1093,1094],{},"Shared auth and control state",[67,1096,1097],{},[111,1098,1099],{},"state/openclaw.sqlite",[67,1101,1102],{},"API keys, OAuth, and the record of everything",[49,1104,1105,1108,1113],{},[67,1106,1107],{},"Per-agent state",[67,1109,1110],{},[111,1111,1112],{},"agents/\u003Cid>/agent/openclaw-agent.sqlite",[67,1114,1115],{},"That agent's auth profiles, sessions, runtime state",[49,1117,1118,1121,1126],{},[67,1119,1120],{},"Channel and provider credentials",[67,1122,1123],{},[111,1124,1125],{},"credentials/",[67,1127,1128],{},"Telegram session, WhatsApp login, Discord pairing",[49,1130,1131,1134,1148],{},[67,1132,1133],{},"Workspace",[67,1135,1136,563,1139,563,1141,563,1143,563,1145],{},[111,1137,1138],{},"AGENTS.md",[111,1140,562],{},[111,1142,566],{},[111,1144,570],{},[111,1146,1147],{},"skills/",[67,1149,1150],{},"Who your agent is and what it remembers",[49,1152,1153,1156,1159],{},[67,1154,1155],{},"Scheduled work",[67,1157,1158],{},"cron jobs, stored in the databases above",[67,1160,1161],{},"Everything that runs unattended",[15,1163,1164,1165,1167,1168,1170],{},"Here's the part that catches people. The config file alone is not enough, and the docs say so directly: shared model auth lives in the SQLite database, agent auth lives in a second one, and channel state lives under ",[111,1166,1125],{},". Copy only ",[111,1169,580],{}," and you'll restore an agent that has forgotten every login it ever had.",[1172,1173,1174],"blockquote",{},[15,1175,1176,1177,563,1180,563,1183,707,1186,1189],{},"Never copy live ",[111,1178,1179],{},".sqlite",[111,1181,1182],{},"-wal",[111,1184,1185],{},"-shm",[111,1187,1188],{},"-journal"," files as a backup. The Gateway writes to them continuously. A raw copy of a live database can be torn or corrupt, and you won't find out until the restore fails.",[15,1191,1192,1193,1196],{},"That's from OpenClaw's own backup guide, and it's why the \"just ",[111,1194,1195],{},"cp -r"," the folder\" advice in most forum threads is only half right. It works if the Gateway is stopped. It's a coin flip if it isn't.",[28,1198,1200],{"id":1199},"the-backup-command","The backup command",[15,1202,1203],{},"One line. Run it before every update.",[104,1205,1207],{"className":106,"code":1206,"language":108,"meta":109,"style":109},"openclaw backup create --output ~/Backups/openclaw --verify\n",[111,1208,1209],{"__ignoreMap":109},[114,1210,1211,1213,1216,1219,1222,1225],{"class":116,"line":117},[114,1212,121],{"class":120},[114,1214,1215],{"class":140}," backup",[114,1217,1218],{"class":140}," create",[114,1220,1221],{"class":124}," --output",[114,1223,1224],{"class":140}," ~/Backups/openclaw",[114,1226,1227],{"class":124}," --verify\n",[15,1229,1230,1231,1234,1235,1237],{},"That writes a timestamped ",[111,1232,1233],{},".tar.gz"," covering the state directory, the config, ",[111,1236,1125],{},", every configured agent directory, and your workspace, then verifies the archive's manifest and payload. It captures the SQLite databases with SQLite's online backup API, so it's safe to run while the Gateway is up. Stopping first is still the safer habit before an update, but the archive itself won't be torn either way.",[15,1239,1240,1241,1244,1245,1248,1249,1252,1253,1256],{},"A few flags worth knowing. ",[111,1242,1243],{},"--dry-run --json"," shows what would be captured without writing anything. ",[111,1246,1247],{},"--no-include-workspace"," skips workspaces if yours are huge or already in Git. ",[111,1250,1251],{},"--only-config"," is a quick config-only snapshot. And ",[111,1254,1255],{},"openclaw backup verify \u003Carchive>"," rechecks an old archive before you rely on it.",[15,1258,1259,1260,1263],{},"Two things the archive deliberately leaves out: plugin ",[111,1261,1262],{},"node_modules/"," trees (rebuildable; reinstall the plugin after a restore) and live session transcripts, cron run logs, and delivery queues (no restoration value). The JSON output reports how many volatile files it skipped so you can see it wasn't an error.",[15,1265,1266],{},"Then note your version, because you'll want it for the rollback section:",[104,1268,1269],{"className":106,"code":107,"language":108,"meta":109,"style":109},[111,1270,1271],{"__ignoreMap":109},[114,1272,1273,1275],{"class":116,"line":117},[114,1274,121],{"class":120},[114,1276,125],{"class":124},[28,1278,1280],{"id":1279},"how-to-restore-after-a-broken-update","How to restore after a broken update",[15,1282,1283],{},"Restore is deliberately two steps: stage, then activate. Nothing overwrites live state in place, and there is no force or in-place mode. That design is what makes it safe, and it's also the source of the disk-space requirement people trip over.",[553,1285,1287],{"id":1286},"stage-the-archive-into-a-fresh-directory","Stage the archive into a fresh directory",[104,1289,1291],{"className":106,"code":1290,"language":108,"meta":109,"style":109},"openclaw backup restore ~/Backups/openclaw/\u003Carchive>.tar.gz --target ./restored-openclaw\n",[111,1292,1293],{"__ignoreMap":109},[114,1294,1295,1297,1299,1302,1305,1309,1312,1316,1319,1321,1324],{"class":116,"line":117},[114,1296,121],{"class":120},[114,1298,1215],{"class":140},[114,1300,1301],{"class":140}," restore",[114,1303,1304],{"class":140}," ~/Backups/openclaw/",[114,1306,1308],{"class":1307},"sD7c4","\u003C",[114,1310,1311],{"class":140},"archiv",[114,1313,1315],{"class":1314},"sgsFI","e",[114,1317,1318],{"class":1307},">",[114,1320,1233],{"class":140},[114,1322,1323],{"class":124}," --target",[114,1325,1326],{"class":140}," ./restored-openclaw\n",[15,1328,1329],{},"The target must be new or empty, and it must not be inside the live state directory. OpenClaw verifies the archive structure, manifest, symlink containment, and every SQLite database before writing. A failed extraction cleans up its own partial output.",[15,1331,1332],{},"This is the disk-space catch: a restore needs enough free space for a full second copy of your state, because it never extracts over the live one. If the staging copy can't be prepared, the restore fails before touching anything. Check free space before you start, and if you're on a small VPS, stage to a mounted volume or clear old archives first.",[553,1334,1336],{"id":1335},"activate-it-offline","Activate it, offline",[1338,1339,1340,1343,1346,1357,1362],"ol",{},[172,1341,1342],{},"Stop the Gateway and any node hosts using the files.",[172,1344,1345],{},"Back up or move aside the current (broken) state directory.",[172,1347,1348,1349,1352,1353,1356],{},"Move the restored state asset into place, or point ",[111,1350,1351],{},"OPENCLAW_STATE_DIR"," at it. Use the archive's ",[111,1354,1355],{},"manifest.json"," for the original paths; don't guess from the default layout.",[172,1358,416,1359,238],{},[111,1360,1361],{},"openclaw doctor",[172,1363,1364,1365,238],{},"Start the Gateway and check ",[111,1366,1367],{},"openclaw health",[15,1369,1370],{},"Restoring an archive is time travel. WhatsApp and other channels with ratchet state may need relinking after a rollback, and pending approvals and delivery state roll back too. Review approvals before you let the agent resume.",[15,1372,1373,1374,1377,1378,1381],{},"After activation, reinstall any plugin that reports missing dependencies with ",[111,1375,1376],{},"openclaw plugins install \u003Cspec> --force",", and run ",[111,1379,1380],{},"openclaw skills list"," to regenerate the skills index.",[15,1383,1384],{},[202,1385],{"alt":1386,"src":1387},"Restore stages first, then you swap: the broken live ~/.openclaw and a staged, verified ./restored-openclaw side by side, needing free disk for both copies, above the sequence stop Gateway, move aside, swap in, doctor, then start.","/img/blog/openclaw-backup-restore-before-update-restore-stages.jpg",[28,1389,1391],{"id":1390},"how-to-roll-back-the-version-itself","How to roll back the version itself",[15,1393,1394,1395,1398],{},"Sometimes the state is fine and the release is the problem. For that, use the updater's own rollback rather than a raw ",[111,1396,1397],{},"npm i -g",", because the updater retains the previous package, runs the required Doctor migrations, and verifies the Gateway comes back:",[104,1400,1402],{"className":106,"code":1401,"language":108,"meta":109,"style":109},"openclaw update --tag \u003Cknown-good-version> --dry-run\nopenclaw update --tag \u003Cknown-good-version>\n",[111,1403,1404,1427],{"__ignoreMap":109},[114,1405,1406,1408,1410,1413,1416,1419,1422,1424],{"class":116,"line":117},[114,1407,121],{"class":120},[114,1409,152],{"class":140},[114,1411,1412],{"class":124}," --tag",[114,1414,1415],{"class":1307}," \u003C",[114,1417,1418],{"class":140},"known-good-versio",[114,1420,1421],{"class":1314},"n",[114,1423,1318],{"class":1307},[114,1425,1426],{"class":124}," --dry-run\n",[114,1428,1429,1431,1433,1435,1437,1439,1441],{"class":116,"line":147},[114,1430,121],{"class":120},[114,1432,152],{"class":140},[114,1434,1412],{"class":124},[114,1436,1415],{"class":1307},[114,1438,1418],{"class":140},[114,1440,1421],{"class":1314},[114,1442,1443],{"class":1307},">\n",[15,1445,1446,1447,1450,1451,1454],{},"It asks for downgrade confirmation. If your channel is extended-stable, add ",[111,1448,1449],{},"--channel stable"," for a one-off exact tag. If the auto-updater is enabled, set ",[111,1452,1453],{},"OPENCLAW_NO_AUTO_UPDATE=1"," in the Gateway's environment during recovery so it doesn't immediately reapply the newer release.",[15,1456,1457,1458,238],{},"One rule the docs are firm on: if the older version refuses to start because the schema or config was migrated forward, do not edit version markers to force it. That's what the pre-update archive is for. Restore it as above, then roll the package back. The full sequence, and the nine specific ways a Gateway fails after an update, is in ",[229,1459,1460],{"href":958},"OpenClaw Gateway won't start after updating",[15,1462,1463],{},[202,1464],{"alt":1465,"src":1466},"Is it the state, or the release? A decision tree: if the state is fine and the release is wrong, run openclaw update --tag with a known-good version and set OPENCLAW_NO_AUTO_UPDATE=1; if the schema migrated forward and the old version refuses to start, restore the pre-update archive first, then roll back the package, and do not edit version markers.","/img/blog/openclaw-backup-restore-before-update-state-or-release.jpg",[28,1468,1470],{"id":1469},"the-habit-in-four-lines","The habit, in four lines",[104,1472,1474],{"className":106,"code":1473,"language":108,"meta":109,"style":109},"openclaw backup create --output ~/Backups/openclaw --verify\nopenclaw --version          # write it down\nopenclaw update\nopenclaw doctor             # and check the defaults that changed\n",[111,1475,1476,1490,1501,1507],{"__ignoreMap":109},[114,1477,1478,1480,1482,1484,1486,1488],{"class":116,"line":117},[114,1479,121],{"class":120},[114,1481,1215],{"class":140},[114,1483,1218],{"class":140},[114,1485,1221],{"class":124},[114,1487,1224],{"class":140},[114,1489,1227],{"class":124},[114,1491,1492,1494,1497],{"class":116,"line":147},[114,1493,121],{"class":120},[114,1495,1496],{"class":124}," --version",[114,1498,1500],{"class":1499},"sAwPA","          # write it down\n",[114,1502,1503,1505],{"class":116,"line":1001},[114,1504,121],{"class":120},[114,1506,221],{"class":140},[114,1508,1510,1512,1514],{"class":116,"line":1509},4,[114,1511,121],{"class":120},[114,1513,253],{"class":140},[114,1515,1516],{"class":1499},"             # and check the defaults that changed\n",[15,1518,1519,1520,1523,1524,1526],{},"That last comment matters this month. The 2026.9.2 release flipped two defaults (swarm on, cross-agent session visibility on) that a clean backup won't protect you from; the ",[229,1521,1522],{"href":231},"2026.9.2 update breakdown"," covers what to review after you're back up. And ",[111,1525,1361],{}," will now nag you if your newest successful backup is more than 14 days old, which is the project's way of saying the same thing this post is.",[28,1528,1530],{"id":1529},"what-betterclaw-does-differently","What BetterClaw does differently",[15,1532,1533,1534,1536],{},"There's no backup step on BetterClaw because you never run the update. We stage releases, snapshot each agent's state before applying, migrate config before restart, and roll the agent back automatically if the release breaks it. Your ",[111,1535,562],{},", memory, credentials, and cron jobs are isolated per agent in their own container and never depend on you remembering a command at 11pm. If you'd rather spend the thirty seconds on your agent than on its infrastructure, that's the whole idea. Free plan, bring your own keys.",[15,1538,1539,1540,390,1544,238],{},"If any of this resonated, give BetterClaw a try. Free plan with 1 agent and 100 credits a month, bring your own API keys, no inference markup. Pro is $49 a month for 5 agents. Updates, backups, and rollbacks are ours to worry about. ",[229,1541,1543],{"href":386,"rel":1542},[388],"Start free",[229,1545,1546],{"href":393},"see full pricing",[15,1548,1549],{},[202,1550],{"alt":1551,"src":1552},"Who remembers the backup at 11pm: on self-hosted OpenClaw you run backup, note version, update, and doctor yourself every time; on BetterClaw the same four steps are staged, snapshotted, migrated, and rolled back for you, per agent and per container.","/img/blog/openclaw-backup-restore-before-update-who-remembers-the-backup.jpg",[28,1554,398],{"id":397},[553,1556,1558],{"id":1557},"what-is-the-correct-way-to-back-up-an-openclaw-agent","What is the correct way to back up an OpenClaw agent?",[15,1560,416,1561,1564,1565,1567,1568,1570,1571,563,1573,1575],{},[111,1562,1563],{},"openclaw backup create --output \u003Cdir> --verify",". It writes a timestamped, verified ",[111,1566,1233],{}," of the state directory (",[111,1569,1059],{}," by default), ",[111,1572,580],{},[111,1574,1125],{},", every agent directory, and your workspace, capturing the SQLite databases safely with the online backup API. Copying the folder by hand only works if the Gateway is stopped, because raw copies of live databases can be corrupt.",[553,1577,1579],{"id":1578},"how-does-openclaw-backup-compare-to-copying-openclaw-manually","How does openclaw backup compare to copying ~/.openclaw manually?",[15,1581,1582,1583,1585,1586,238],{},"The command is safe with the Gateway running, verifies the archive, skips volatile files that have no restoration value, and records a manifest so restore knows the original paths. A manual copy is fine only if the Gateway is stopped first, and it's easy to miss the workspace if it lives outside the state directory. Either way, copying just ",[111,1584,580],{}," is not a backup: auth and channel state live in SQLite and ",[111,1587,1125],{},[553,1589,1591],{"id":1590},"how-do-i-restore-an-openclaw-backup-after-an-update-breaks-my-setup","How do I restore an OpenClaw backup after an update breaks my setup?",[15,1593,1594,1595,1598,1599,1601,1602,1604],{},"Stage it first with ",[111,1596,1597],{},"openclaw backup restore \u003Carchive> --target \u003Cnew-empty-dir>",", which verifies and extracts without touching live state. Then stop the Gateway, move the broken state directory aside, move the restored one into place (or point ",[111,1600,1351],{}," at it), run ",[111,1603,1361],{},", and start. Expect to relink WhatsApp and review pending approvals, since restore rolls those back too.",[553,1606,1608],{"id":1607},"how-much-disk-space-does-an-openclaw-restore-need","How much disk space does an OpenClaw restore need?",[15,1610,1611,1612,1614],{},"Enough for a full second copy of your state directory and workspace, because restore extracts to a fresh target and never overwrites in place. If the staging copy can't be created, the restore fails before changing anything. On a small VPS, clear old archives or stage to a mounted volume first, and consider ",[111,1613,1247],{}," if your workspace is large and already in Git.",[553,1616,1618],{"id":1617},"is-it-safe-to-keep-openclaw-backups-on-the-same-server","Is it safe to keep OpenClaw backups on the same server?",[15,1620,1621],{},"It's better than nothing and worse than offsite. Archives contain auth profiles, channel credentials, and full session history, so store them encrypted with permissions as tight as the live state directory, and copy them off the machine (the docs show rclone to an S3-compatible bucket). If you suspect an archive leaked, rotate the credentials in it. For continuous protection, the docs also cover Litestream replication of the databases.",[451,1623,1624],{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sD7c4, html code.shiki .sD7c4{--shiki-default:#D73A49}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}",{"title":109,"searchDepth":147,"depth":147,"links":1626},[1627,1628,1629,1633,1634,1635,1636],{"id":1052,"depth":147,"text":1053},{"id":1199,"depth":147,"text":1200},{"id":1279,"depth":147,"text":1280,"children":1630},[1631,1632],{"id":1286,"depth":1001,"text":1287},{"id":1335,"depth":1001,"text":1336},{"id":1390,"depth":147,"text":1391},{"id":1469,"depth":147,"text":1470},{"id":1529,"depth":147,"text":1530},{"id":397,"depth":147,"text":398,"children":1637},[1638,1639,1640,1641,1642],{"id":1557,"depth":1001,"text":1558},{"id":1578,"depth":1001,"text":1579},{"id":1590,"depth":1001,"text":1591},{"id":1607,"depth":1001,"text":1608},{"id":1617,"depth":1001,"text":1618},"2026-09-11","Back up your OpenClaw agent before updating: which directories to copy, how to restore if the update breaks your setup, and the 9.2 disk space requirement.","/img/blog/openclaw-backup-restore-before-update.jpg",{},{"title":1037,"description":1644},"How to Back Up and Restore an OpenClaw Agent (2026)","blog/openclaw-backup-restore-before-update",[1651,1652,1653,1654,1655,1656,1657,1658],"openclaw backup","openclaw restore","openclaw backup before update","openclaw backup command","openclaw rollback version","openclaw state directory","back up openclaw agent","openclaw update broke","-MWA7ql6aUBZoPVb9PG3UYP_6dMp0_S1zooXqiF2DoU",{"id":1661,"title":1662,"author":1663,"body":1664,"category":465,"date":3060,"description":3061,"extension":468,"featured":469,"hideToc":469,"image":3062,"imageAlt":474,"imageHeight":472,"imageWidth":473,"lang":474,"meta":3063,"navigation":476,"noindex":469,"path":958,"readingTime":3064,"redirected":469,"relatedSlugs":474,"seo":3065,"seoTitle":3066,"stem":3067,"tags":3068,"updatedDate":3078,"__hash__":3079},"blog/blog/openclaw-gateway-wont-start-after-update.md","OpenClaw Gateway Won't Start After Updating: Every Crash Loop and Its Fix",{"name":7,"role":8,"avatar":9},{"type":12,"value":1665,"toc":3037},[1666,1669,1678,1681,1685,1688,1739,1758,1768,1771,1777,1781,1790,1800,1806,1859,1869,1873,1881,1893,1898,1931,1934,1938,1946,1961,1965,1997,2011,2015,2028,2033,2038,2078,2083,2087,2099,2104,2109,2164,2172,2176,2185,2193,2198,2249,2270,2274,2282,2290,2298,2302,2310,2323,2328,2354,2362,2378,2429,2442,2466,2469,2515,2526,2530,2537,2546,2550,2598,2623,2627,2642,2655,2677,2688,2693,2757,2764,2771,2777,2781,2784,2805,2808,2869,2888,2898,2904,2910,2913,2917,2920,2929,2937,2939,2943,2951,2955,2965,2969,2986,2990,3008,3012,3018,3022,3035],[15,1667,1668],{},"The update said it succeeded. The Gateway says otherwise. Here are the ten failures people actually hit after an OpenClaw update, matched to the exact log line each one prints, with the fix and the rollback for each.",[15,1670,1671,1673,1674,1677],{},[111,1672,419],{}," finishes. It prints a version number. You go to send a message and nothing answers. ",[111,1675,1676],{},"openclaw gateway status"," says stopped, or says running with the port closed, or the log is a wall of the same three lines every sixteen seconds because launchd keeps restarting a process that keeps dying.",[15,1679,1680],{},"This happens often enough that the project's own troubleshooting runbook has a section titled \"After an update.\" What that runbook doesn't do is walk you through each distinct failure with the log signature that identifies it. That's this post. Find your log line, jump to its section, skip the rest.",[28,1682,1684],{"id":1683},"the-first-sixty-seconds-in-order","The first sixty seconds, in order",[15,1686,1687],{},"Before diagnosing anything, run the official command ladder. It fixes a surprising share of post-update breakage on its own and surfaces the log line you need for the rest.",[104,1689,1691],{"className":106,"code":1690,"language":108,"meta":109,"style":109},"openclaw status --all\nopenclaw update status --json\nopenclaw gateway status --deep\nopenclaw doctor --fix\nopenclaw gateway restart\n",[111,1692,1693,1701,1711,1722,1730],{"__ignoreMap":109},[114,1694,1695,1697,1699],{"class":116,"line":117},[114,1696,121],{"class":120},[114,1698,141],{"class":140},[114,1700,144],{"class":124},[114,1702,1703,1705,1707,1709],{"class":116,"line":147},[114,1704,121],{"class":120},[114,1706,152],{"class":140},[114,1708,141],{"class":140},[114,1710,157],{"class":124},[114,1712,1713,1715,1717,1719],{"class":116,"line":1001},[114,1714,121],{"class":120},[114,1716,263],{"class":140},[114,1718,141],{"class":140},[114,1720,1721],{"class":124}," --deep\n",[114,1723,1724,1726,1728],{"class":116,"line":1509},[114,1725,121],{"class":120},[114,1727,253],{"class":140},[114,1729,256],{"class":124},[114,1731,1733,1735,1737],{"class":116,"line":1732},5,[114,1734,121],{"class":120},[114,1736,263],{"class":140},[114,1738,266],{"class":140},[15,1740,1741,1742,1745,1746,1749,1750,1753,1754,1757],{},"Then read the logs. ",[111,1743,1744],{},"openclaw logs --follow"," is the preferred path. If the Gateway won't stay up long enough to serve logs, go to the files: ",[111,1747,1748],{},"/tmp/openclaw/openclaw-YYYY-MM-DD.log"," by default, ",[111,1751,1752],{},"~/.openclaw/logs/gateway.err.log"," on a macOS LaunchAgent install, or ",[111,1755,1756],{},"journalctl --user -u openclaw-gateway.service -n 200 --no-pager"," on Linux systemd.",[15,1759,1760,1761,1764,1765,1767],{},"If the Gateway is healthy after ",[111,1762,1763],{},"doctor --fix"," and a restart, you're done. If not, match the log to one of the ten below. If you are on 2026.9.4, read section 10 first, because on that release ",[111,1766,1763],{}," itself can be the thing that fails.",[15,1769,1770],{},"An update that prints \"success\" has only proven that npm finished. Whether the files on disk are complete, the config still validates, and the service came back up are three separate questions.",[15,1772,1773],{},[202,1774],{"alt":1775,"src":1776},"The first sixty seconds: a five-rung ladder of commands, branching to \"healthy? stop here\" after doctor --fix and \"still down? match the log line\" after the restart.","/img/blog/openclaw-gateway-wont-start-after-update-first-sixty-seconds.jpg",[28,1778,1780],{"id":1779},"_1-err_module_not_found-pointing-at-a-file-in-dist","1. ERR_MODULE_NOT_FOUND pointing at a file in dist/",[15,1782,1783,1786,1787],{},[19,1784,1785],{},"The log:"," ",[111,1788,1789],{},"Cannot find module '.../node_modules/openclaw/dist/\u003Csomething>.js'",[15,1791,1792,1795,1796,1799],{},[19,1793,1794],{},"What happened:"," the install is incomplete. The clearest documented case was the 2026.4.24 npm release, where a postinstall step timed out (",[111,1797,1798],{},"spawnSync /usr/bin/node ETIMEDOUT"," in the install output) and silently pruned 1,617 of the package's 4,116 dist files on Linux. The update reported success. The Gateway then failed on every start because the modules it imported no longer existed, and plugin runtime directories held symlinks pointing at nothing.",[15,1801,1802,1805],{},[19,1803,1804],{},"The fix:"," don't try to repair the tree. Reinstall cleanly, and if the current version is the problem, pin the last known good one.",[104,1807,1809],{"className":106,"code":1808,"language":108,"meta":109,"style":109},"openclaw gateway stop\nnpm install -g openclaw@\u003Cprevious-version>\nopenclaw doctor --fix\nopenclaw gateway restart\n",[111,1810,1811,1820,1843,1851],{"__ignoreMap":109},[114,1812,1813,1815,1817],{"class":116,"line":117},[114,1814,121],{"class":120},[114,1816,263],{"class":140},[114,1818,1819],{"class":140}," stop\n",[114,1821,1822,1825,1828,1831,1834,1836,1839,1841],{"class":116,"line":147},[114,1823,1824],{"class":120},"npm",[114,1826,1827],{"class":140}," install",[114,1829,1830],{"class":124}," -g",[114,1832,1833],{"class":140}," openclaw@",[114,1835,1308],{"class":1307},[114,1837,1838],{"class":140},"previous-versio",[114,1840,1421],{"class":1314},[114,1842,1443],{"class":1307},[114,1844,1845,1847,1849],{"class":116,"line":1001},[114,1846,121],{"class":120},[114,1848,253],{"class":140},[114,1850,256],{"class":124},[114,1852,1853,1855,1857],{"class":116,"line":1509},[114,1854,121],{"class":120},[114,1856,263],{"class":140},[114,1858,266],{"class":140},[15,1860,1861,1862,1865,1866,1868],{},"Verify with ",[111,1863,1864],{},"ls node_modules/openclaw/dist | wc -l"," before and after if you want to see the difference. If reinstalling the current version keeps losing files, the postinstall is timing out on your machine; a slow disk or a starved container will do it. Pin, wait for the next release, and read the ",[229,1867,237],{"href":236}," guide's section on staged updates before trying again.",[28,1870,1872],{"id":1871},"_2-the-update-ran-while-the-gateway-was-still-running-macos","2. The update ran while the Gateway was still running (macOS)",[15,1874,1875,1877,1878,1880],{},[19,1876,1785],{}," varies, but the shape is \"crash immediately after ",[111,1879,419],{},",\" often with module or JSON parse errors on files that look fine a minute later.",[15,1882,1883,1885,1886,1888,1889,1892],{},[19,1884,1794],{}," on macOS, ",[111,1887,419],{}," has historically run npm's file replacement while the LaunchAgent still had the old process holding those files open. npm can't cleanly overwrite files a live Node process has mapped, ",[111,1890,1891],{},"launchctl kickstart -k"," then restarts against a half-written tree, and you get a Gateway that dies on boot. Issue #66390 documents it as consistent across versions.",[15,1894,1895,1897],{},[19,1896,1804],{}," stop the service yourself before updating, then start it yourself after.",[104,1899,1901],{"className":106,"code":1900,"language":108,"meta":109,"style":109},"launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist\nopenclaw update --no-restart\nlaunchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n",[111,1902,1903,1914,1922],{"__ignoreMap":109},[114,1904,1905,1908,1911],{"class":116,"line":117},[114,1906,1907],{"class":120},"launchctl",[114,1909,1910],{"class":140}," unload",[114,1912,1913],{"class":140}," ~/Library/LaunchAgents/ai.openclaw.gateway.plist\n",[114,1915,1916,1918,1920],{"class":116,"line":147},[114,1917,121],{"class":120},[114,1919,152],{"class":140},[114,1921,683],{"class":124},[114,1923,1924,1926,1929],{"class":116,"line":1001},[114,1925,1907],{"class":120},[114,1927,1928],{"class":140}," load",[114,1930,1913],{"class":140},[15,1932,1933],{},"The September 2026.9.2 release improved this path (Gateway restarts after Git updates are restored, and chat-triggered updates now report success, failure, or skip with recovery guidance), but stop-then-update remains the safe habit on any supervised install.",[28,1935,1937],{"id":1936},"_3-invalid-config-unrecognized-key-or-config-validation-failed","3. Invalid config, Unrecognized key, or config validation failed",[15,1939,1940,1786,1942,1945],{},[19,1941,1785],{},[111,1943,1944],{},"Gateway rejected invalid config"," on startup, or hot-reload logs saying it skipped an invalid edit.",[15,1947,1948,1950,1951,1953,1954,422,1957,1960],{},[19,1949,1794],{}," the config schema moved and your ",[111,1952,580],{}," didn't. A key that was valid last month is unknown now, or a new key was written by the update that an older component can't read. This is also the classic post-rollback failure: newer releases add plugin entries (2026.4.24 added ",[111,1955,1956],{},"plugins.entries.feishu",[111,1958,1959],{},"plugins.entries.whatsapp",") that require that version or later, so if you downgrade, the config still references them and the older Gateway refuses to boot.",[15,1962,1963],{},[19,1964,1804],{},[104,1966,1968],{"className":106,"code":1967,"language":108,"meta":109,"style":109},"openclaw config file\nopenclaw config validate\nopenclaw doctor --fix\n",[111,1969,1970,1980,1989],{"__ignoreMap":109},[114,1971,1972,1974,1977],{"class":116,"line":117},[114,1973,121],{"class":120},[114,1975,1976],{"class":140}," config",[114,1978,1979],{"class":140}," file\n",[114,1981,1982,1984,1986],{"class":116,"line":147},[114,1983,121],{"class":120},[114,1985,1976],{"class":140},[114,1987,1988],{"class":140}," validate\n",[114,1990,1991,1993,1995],{"class":116,"line":1001},[114,1992,121],{"class":120},[114,1994,253],{"class":140},[114,1996,256],{"class":124},[15,1998,1999,2002,2003,2005,2006,2010],{},[111,2000,2001],{},"config validate"," names the offending key. ",[111,2004,1763],{}," removes or migrates known drift, including cleaning out those version-gated plugin entries after a rollback. If you edited the file by hand, remember it's JSON5; a trailing comma or comment that was fine before a parser change can be the whole problem. The ",[229,2007,2009],{"href":2008},"/tools/agent-error-decoder/openclaw-config-validation-failed","config validation failed"," decoder covers the specific key errors.",[28,2012,2014],{"id":2013},"_4-tight-crash-loop-with-an-unhandled-promise-rejection","4. Tight crash loop with an unhandled promise rejection",[15,2016,2017,2019,2020,2023,2024,2027],{},[19,2018,1785],{}," the same stack trace every ten to twenty seconds, ending in an unhandled rejection from a plugin or subsystem. The documented case is ",[111,2021,2022],{},"[plugins] bonjour: watchdog detected non-announced service"," followed by ",[111,2025,2026],{},"CIAO ANNOUNCEMENT CANCELLED",", on 2026.4.24, Apple Silicon.",[15,2029,2030,2032],{},[19,2031,1794],{}," a watchdog restarted the mDNS advertiser when it stayed in \"announcing\" past about eight seconds. The cancellation surfaced as a rejected promise nobody was awaiting, the process died, launchd restarted it, and the loop repeated every sixteen seconds. Downgrading fixed it instantly.",[15,2034,2035,2037],{},[19,2036,1804],{}," this class of bug is version-specific, and the honest fix is to go back one version until the patch lands.",[104,2039,2041],{"className":106,"code":2040,"language":108,"meta":109,"style":109},"npm i -g openclaw@\u003Cprevious-version>\nopenclaw doctor --fix\nopenclaw gateway restart\n",[111,2042,2043,2062,2070],{"__ignoreMap":109},[114,2044,2045,2047,2050,2052,2054,2056,2058,2060],{"class":116,"line":117},[114,2046,1824],{"class":120},[114,2048,2049],{"class":140}," i",[114,2051,1830],{"class":124},[114,2053,1833],{"class":140},[114,2055,1308],{"class":1307},[114,2057,1838],{"class":140},[114,2059,1421],{"class":1314},[114,2061,1443],{"class":1307},[114,2063,2064,2066,2068],{"class":116,"line":147},[114,2065,121],{"class":120},[114,2067,253],{"class":140},[114,2069,256],{"class":124},[114,2071,2072,2074,2076],{"class":116,"line":1001},[114,2073,121],{"class":120},[114,2075,263],{"class":140},[114,2077,266],{"class":140},[15,2079,416,2080,2082],{},[111,2081,1763],{}," after the downgrade, not before, so it can strip the config keys the newer version wrote (see section 3). Then check the release notes and issue tracker for your exact log line before you try the new version again.",[28,2084,2086],{"id":2085},"_5-the-process-dies-with-no-error-and-dmesg-says-oom","5. The process dies with no error, and dmesg says OOM",[15,2088,2089,2091,2092,390,2095,2098],{},[19,2090,1785],{}," nothing useful in the Gateway log. ",[111,2093,2094],{},"journalctl",[111,2096,2097],{},"dmesg"," shows the kernel's OOM killer taking the process, often during \"sidecar startup\" right after boot.",[15,2100,2101,2103],{},[19,2102,1794],{}," newer releases start more at boot (sidecars, plugin runtimes, embedding caches), and on a small Linux box the startup spike exceeds available memory. The OOM killer stops the process, systemd or npm restarts it immediately with no delay, the same spike hits again, and you have an infinite loop that looks like a crash but is actually a resource ceiling. Reported on Ubuntu 24 npm installs from 2026.4.24 onward.",[15,2105,2106,2108],{},[19,2107,1804],{}," confirm it first, because it's easy to misdiagnose.",[104,2110,2112],{"className":106,"code":2111,"language":108,"meta":109,"style":109},"dmesg -T | grep -i \"killed process\"\njournalctl --user -u openclaw-gateway.service -n 200 --no-pager | grep -i oom\n",[111,2113,2114,2133],{"__ignoreMap":109},[114,2115,2116,2118,2121,2124,2127,2130],{"class":116,"line":117},[114,2117,2097],{"class":120},[114,2119,2120],{"class":124}," -T",[114,2122,2123],{"class":1307}," |",[114,2125,2126],{"class":120}," grep",[114,2128,2129],{"class":124}," -i",[114,2131,2132],{"class":140}," \"killed process\"\n",[114,2134,2135,2137,2140,2143,2146,2149,2152,2155,2157,2159,2161],{"class":116,"line":147},[114,2136,2094],{"class":120},[114,2138,2139],{"class":124}," --user",[114,2141,2142],{"class":124}," -u",[114,2144,2145],{"class":140}," openclaw-gateway.service",[114,2147,2148],{"class":124}," -n",[114,2150,2151],{"class":124}," 200",[114,2153,2154],{"class":124}," --no-pager",[114,2156,2123],{"class":1307},[114,2158,2126],{"class":120},[114,2160,2129],{"class":124},[114,2162,2163],{"class":140}," oom\n",[15,2165,2166,2167,2171],{},"Then either give the box more memory, add swap as a stopgap, or add a restart delay to the systemd unit so the loop can't spin. Disable plugins you don't use; each one adds startup memory. The ",[229,2168,2170],{"href":2169},"/blog/openclaw-oom-errors","OpenClaw OOM errors"," post has the sizing numbers.",[28,2173,2175],{"id":2174},"_6-eaddrinuse-or-port-18789-is-already-in-use","6. EADDRINUSE or \"Port 18789 is already in use\"",[15,2177,2178,2180,2181,2184],{},[19,2179,1785],{}," exactly that, or ",[111,2182,2183],{},"gateway status"," says running while the connectivity probe fails.",[15,2186,2187,2189,2190,2192],{},[19,2188,1794],{}," two things think they own the port. The most common post-update version is a split-brain install: the update put a new ",[111,2191,121],{}," somewhere, the supervisor is still pointing at the old one, and both try to bind. The docs call it out by name.",[15,2194,2195,2197],{},[19,2196,1804],{}," find the duplicate, then reinstall the service from the install you actually want.",[104,2199,2201],{"className":106,"code":2200,"language":108,"meta":109,"style":109},"which -a openclaw\nopenclaw --version\nopenclaw gateway status --deep\nopenclaw gateway install --force\nopenclaw gateway restart\n",[111,2202,2203,2214,2220,2230,2241],{"__ignoreMap":109},[114,2204,2205,2208,2211],{"class":116,"line":117},[114,2206,2207],{"class":124},"which",[114,2209,2210],{"class":124}," -a",[114,2212,2213],{"class":140}," openclaw\n",[114,2215,2216,2218],{"class":116,"line":147},[114,2217,121],{"class":120},[114,2219,125],{"class":124},[114,2221,2222,2224,2226,2228],{"class":116,"line":1001},[114,2223,121],{"class":120},[114,2225,263],{"class":140},[114,2227,141],{"class":140},[114,2229,1721],{"class":124},[114,2231,2232,2234,2236,2238],{"class":116,"line":1509},[114,2233,121],{"class":120},[114,2235,263],{"class":140},[114,2237,1827],{"class":140},[114,2239,2240],{"class":124}," --force\n",[114,2242,2243,2245,2247],{"class":116,"line":1732},[114,2244,121],{"class":120},[114,2246,263],{"class":140},[114,2248,266],{"class":140},[15,2250,2251,2254,2255,2258,2259,390,2261,2264,2265,2269],{},[111,2252,2253],{},"which -a"," showing two paths is your answer. If you changed ",[111,2256,2257],{},"gateway.port"," at any point, the supervisor unit keeps the old port until ",[111,2260,1763],{},[111,2262,2263],{},"gateway install --force"," rewrites it. The ",[229,2266,2268],{"href":2267},"/tools/agent-error-decoder/openclaw-port-18789-in-use","port 18789 in use"," decoder handles the non-update variants.",[28,2271,2273],{"id":2272},"_7-protocol-mismatch-after-a-rollback","7. protocol mismatch after a rollback",[15,2275,2276,1786,2278,2281],{},[19,2277,1785],{},[111,2279,2280],{},"protocol mismatch ... client=... min= max= expected=",", repeating, after you downgraded.",[15,2283,2284,2286,2287,2289],{},[19,2285,1794],{}," the old Gateway is running fine. A newer client process (a dashboard, an editor integration, a long-running ",[111,2288,1744],{}," shell, an app-server helper) is still trying to reconnect with a protocol range the older Gateway can't speak. The Gateway isn't broken; it's correctly refusing a client from the future.",[15,2291,2292,1786,2294,2297],{},[19,2293,1804],{},[111,2295,2296],{},"openclaw gateway status --deep"," lists established clients with PIDs and command lines. Stop or restart the one whose command line points at the newer install. Restart any apps that embed OpenClaw. Do not try to make the old Gateway accept the new protocol; the version gate is there to stop exactly the corruption you're avoiding.",[28,2299,2301],{"id":2300},"_8-plugin-load-failure-after-a-partial-upgrade","8. Plugin load failure after a partial upgrade",[15,2303,2304,1786,2306,2309],{},[19,2305,1785],{},[111,2307,2308],{},"plugin ... failed to load",", a plugin blocked by dangerous-code scanning during the update, or a plugin referencing an SDK alias that no longer exists.",[15,2311,2312,2314,2315,2318,2319,2322],{},[19,2313,1794],{}," plugins update on their own schedule, and an update can leave one of them referencing core modules that moved. Two documented shapes: plugin updates failing with ",[111,2316,2317],{},"ERR_MODULE_NOT_FOUND"," against a dist file while core was mid-update (2026.4.9 on macOS), and, from September 8, 2026, the removal window opening for deprecated untrusted-named prompt-context aliases in the Plugin SDK. A plugin that never migrated to the channel-named fields and ",[111,2320,2321],{},"buildChannelMetadata"," can stop loading on a current core.",[15,2324,2325,2327],{},[19,2326,1804],{}," disable the failing plugin, get the Gateway up, then deal with the plugin.",[104,2329,2331],{"className":106,"code":2330,"language":108,"meta":109,"style":109},"openclaw doctor --fix\n# if a specific plugin is named in the log, disable it in openclaw.json and restart\nopenclaw gateway restart\n",[111,2332,2333,2341,2346],{"__ignoreMap":109},[114,2334,2335,2337,2339],{"class":116,"line":117},[114,2336,121],{"class":120},[114,2338,253],{"class":140},[114,2340,256],{"class":124},[114,2342,2343],{"class":116,"line":147},[114,2344,2345],{"class":1499},"# if a specific plugin is named in the log, disable it in openclaw.json and restart\n",[114,2347,2348,2350,2352],{"class":116,"line":1001},[114,2349,121],{"class":120},[114,2351,263],{"class":140},[114,2353,266],{"class":140},[15,2355,2356,2357,2361],{},"2026.9.2 added repair of retired plugin install configuration before service startup and stopped warning about intentionally disabled plugins, so on a current version this section is shorter than it used to be. Check the plugin's own changelog for a compatible release; the ",[229,2358,2360],{"href":2359},"/blog/clawhub-skills-security-audit","ClawHub skills security audit"," post covers what to do when the blocker is the dangerous-code scan rather than a missing module.",[15,2363,2364,2370,2371,2374,2375,2377],{},[19,2365,2366,2367,2369],{},"The variant ",[111,2368,1763],{}," cannot repair."," If the Gateway loops without ever reporting ready and the log points at plugin install metadata, you have the conflict tracked as issue #108528: the startup migration finds one plugin recorded differently in the legacy ",[111,2372,2373],{},"plugins/installs.json"," and the newer shared SQLite plugin index, and refuses to continue. ",[111,2376,1763],{}," does not reconcile the two. This is the failure behind the reports of people running the repair eleven times in a row; the pass count was never the problem. Reconcile it by hand, letting the SQLite index win:",[104,2379,2381],{"className":106,"code":2380,"language":108,"meta":109,"style":109},"openclaw gateway stop\nmv ~/.openclaw/plugins/installs.json ~/.openclaw/plugins/installs.json.bak\nopenclaw plugins install \u003Cplugin-id>\nopenclaw gateway restart\n",[111,2382,2383,2391,2402,2421],{"__ignoreMap":109},[114,2384,2385,2387,2389],{"class":116,"line":117},[114,2386,121],{"class":120},[114,2388,263],{"class":140},[114,2390,1819],{"class":140},[114,2392,2393,2396,2399],{"class":116,"line":147},[114,2394,2395],{"class":120},"mv",[114,2397,2398],{"class":140}," ~/.openclaw/plugins/installs.json",[114,2400,2401],{"class":140}," ~/.openclaw/plugins/installs.json.bak\n",[114,2403,2404,2406,2409,2411,2413,2416,2419],{"class":116,"line":1001},[114,2405,121],{"class":120},[114,2407,2408],{"class":140}," plugins",[114,2410,1827],{"class":140},[114,2412,1415],{"class":1307},[114,2414,2415],{"class":140},"plugin-i",[114,2417,2418],{"class":1314},"d",[114,2420,1443],{"class":1307},[114,2422,2423,2425,2427],{"class":116,"line":1509},[114,2424,121],{"class":120},[114,2426,263],{"class":140},[114,2428,266],{"class":140},[15,2430,2431,2434,2435,2438,2439,2441],{},[19,2432,2433],{},"If the plugin used to be built in, it is not missing, it moved."," WhatsApp, Discord, Brave, Perplexity and roughly twenty other channel and provider extensions became external ",[111,2436,2437],{},"@openclaw/*"," packages at 2026.5.2, and the migration installed none of them automatically (issue #77483). A config that still references one produces a failed load on every start. Reinstall the ones you actually use, then let ",[111,2440,1763],{}," clear the references you do not:",[104,2443,2445],{"className":106,"code":2444,"language":108,"meta":109,"style":109},"openclaw plugins install @openclaw/whatsapp\nopenclaw doctor --fix\n",[111,2446,2447,2458],{"__ignoreMap":109},[114,2448,2449,2451,2453,2455],{"class":116,"line":117},[114,2450,121],{"class":120},[114,2452,2408],{"class":140},[114,2454,1827],{"class":140},[114,2456,2457],{"class":140}," @openclaw/whatsapp\n",[114,2459,2460,2462,2464],{"class":116,"line":147},[114,2461,121],{"class":120},[114,2463,253],{"class":140},[114,2465,256],{"class":124},[15,2467,2468],{},"Non-interactive shells are where this bites twice. Installing a plugin that needs capability consent cannot prompt, so it fails in a script or a provisioning run unless you grant consent explicitly:",[104,2470,2472],{"className":106,"code":2471,"language":108,"meta":109,"style":109},"openclaw plugins install clawhub:\u003Cpackage> --accept-capabilities\nopenclaw plugins update \u003Cplugin-id> --accept-capabilities\n",[111,2473,2474,2497],{"__ignoreMap":109},[114,2475,2476,2478,2480,2482,2485,2487,2490,2492,2494],{"class":116,"line":117},[114,2477,121],{"class":120},[114,2479,2408],{"class":140},[114,2481,1827],{"class":140},[114,2483,2484],{"class":140}," clawhub:",[114,2486,1308],{"class":1307},[114,2488,2489],{"class":140},"packag",[114,2491,1315],{"class":1314},[114,2493,1318],{"class":1307},[114,2495,2496],{"class":124}," --accept-capabilities\n",[114,2498,2499,2501,2503,2505,2507,2509,2511,2513],{"class":116,"line":147},[114,2500,121],{"class":120},[114,2502,2408],{"class":140},[114,2504,152],{"class":140},[114,2506,1415],{"class":1307},[114,2508,2415],{"class":140},[114,2510,2418],{"class":1314},[114,2512,1318],{"class":1307},[114,2514,2496],{"class":124},[15,2516,2517,2518,2521,2522,2525],{},"Bundled and verified first-party plugins do not need the flag. Third-party ones do, and Perplexity is the one people trip over, because it ships as its own plugin (",[111,2519,2520],{},"@openclaw/perplexity-plugin",") rather than a provider you can simply configure. A config naming Perplexity on a host where that plugin was never installed and consented to will keep failing its load every start. Our ",[229,2523,2524],{"href":231},"plugin externalization breakdown"," lists everything that moved.",[28,2527,2529],{"id":2528},"_9-runtime-stopped-and-no-service-or-refusing-to-bind-gateway-without-auth","9. Runtime: stopped and \"no service,\" or \"refusing to bind gateway without auth\"",[15,2531,2532,1786,2534,2536],{},[19,2533,1785],{},[111,2535,2183],{}," reports no supervised service at all, or the last gateway error mentions refusing to bind without auth.",[15,2538,2539,2541,2542,2545],{},[19,2540,1794],{}," the update rewrote or dropped the supervisor config (launchd plist, systemd unit, scheduled task), or your ",[111,2543,2544],{},"gateway.bind"," is non-loopback and the update's stricter defaults now refuse to start without an auth token configured.",[15,2547,2548],{},[19,2549,1804],{},[104,2551,2553],{"className":106,"code":2552,"language":108,"meta":109,"style":109},"openclaw gateway install --force\nopenclaw gateway restart\n# Linux user services: survive logout\nsudo loginctl enable-linger \"$USER\"\n",[111,2554,2555,2565,2573,2578],{"__ignoreMap":109},[114,2556,2557,2559,2561,2563],{"class":116,"line":117},[114,2558,121],{"class":120},[114,2560,263],{"class":140},[114,2562,1827],{"class":140},[114,2564,2240],{"class":124},[114,2566,2567,2569,2571],{"class":116,"line":147},[114,2568,121],{"class":120},[114,2570,263],{"class":140},[114,2572,266],{"class":140},[114,2574,2575],{"class":116,"line":1001},[114,2576,2577],{"class":1499},"# Linux user services: survive logout\n",[114,2579,2580,2583,2586,2589,2592,2595],{"class":116,"line":1509},[114,2581,2582],{"class":120},"sudo",[114,2584,2585],{"class":140}," loginctl",[114,2587,2588],{"class":140}," enable-linger",[114,2590,2591],{"class":140}," \"",[114,2593,2594],{"class":1314},"$USER",[114,2596,2597],{"class":140},"\"\n",[15,2599,2600,2601,2603,2604,2607,2608,422,2611,2614,2615,2618,2619,2622],{},"For the auth refusal, either keep ",[111,2602,2544],{}," on loopback and reach the host over SSH (",[111,2605,2606],{},"ssh -N -L 18789:127.0.0.1:18789 user@host","), or set ",[111,2609,2610],{},"gateway.auth.mode",[111,2612,2613],{},"gateway.auth.token"," and restart. Also watch for ",[111,2616,2617],{},"Gateway start blocked: set gateway.mode=local"," if a remote mode is set without the expected local stamp; the ",[229,2620,2621],{"href":371},"OpenClaw gateway guide"," explains the modes.",[28,2624,2626],{"id":2625},"_10-202694-existing-managed-handoff-lease-is-incompatible","10. 2026.9.4: \"existing managed handoff lease is incompatible\"",[15,2628,2629,1786,2631,2634,2635,422,2638,2641],{},[19,2630,1785],{},[111,2632,2633],{},"existing managed handoff lease is incompatible; retain diagnostics and run openclaw triage manually",", on every config write. On the managed-update path you may also see ",[111,2636,2637],{},"[sqlite/transaction] slow SQLite transaction hold",[111,2639,2640],{},"[infra/exec-approvals] exec approvals SQLite state is unavailable; denying host execution"," before the update gives up.",[15,2643,2644,2646,2647,2650,2651,2654],{},[19,2645,1794],{}," this one is a release-cut accident, and it is the newest thing on the list. The fix for it, PR #144208, ",[111,2648,2649],{},"fix(update): keep retired handoff records from refusing unrelated sources",", landed on main as commit ",[111,2652,2653],{},"00edac8"," at 17:16 UTC on 10 September 2026 — after the 2026.9.4 release branch had already been cut. 2026.9.4 published on 11 September without it, and as of this writing there is no 2026.9.5. It is tracked as issue #144742, still open, labelled a release blocker.",[15,2656,2657,2658,2661,2662,2661,2665,2668,2669,2672,2673,2676],{},"The mechanism is narrow and unlucky. Every config write on 2026.9.4 goes through ",[111,2659,2660],{},"withConfigWriteLock"," → ",[111,2663,2664],{},"assertSourceUnborrowed",[111,2666,2667],{},"readRetainedSources",", which scans every row in the machine-global handoff lease store and throws on any payload the current schema cannot parse. Older updaters wrote ",[111,2670,2671],{},"{\"version\":1,...}"," rows into that same table. The 2026.9.4 schema accepts only versions 2 and 3. So one leftover row from a previous update, on a host that has updated before, fails every config write from then on: ",[111,2674,2675],{},"openclaw config set",", Doctor repairs, plugin convergence, and even an already-current update.",[15,2678,2679,2680,2683,2684,2687],{},"Worth being precise about, because it doesn't look like the other nine: this is not a tight crash loop. The Gateway may be running and simply unconfigurable, or it may be down after a managed update rolled back. That second path is the nastier one. Issue #145192 documents a 2026.9.2 → 2026.9.4 managed update failing at candidate-Doctor on a ",[503,2681,2682],{},"live"," v1 lease — the cleanup escape hatch, ",[111,2685,2686],{},"canCleanupLegacyManagedHandoff",", requires the lease owner process to be dead, and during a self-update the owner is very much alive. The package then rolls back to 2026.9.2 while the state migrations 2026.9.4 already applied stay applied, which leaves you running an old binary against a newer data schema. That is the worst state on this whole page, because neither version is wrong on its own.",[15,2689,2690,2692],{},[19,2691,1804],{}," delete the lease store and install 2026.9.4 directly rather than through the managed update path.",[104,2694,2696],{"className":106,"code":2695,"language":108,"meta":109,"style":109},"openclaw gateway stop\nrm -f \"${TMPDIR:-/tmp}/openclaw/managed-update-handoffs.sqlite\"\nnpm install -g openclaw@2026.9.4\nopenclaw doctor --non-interactive\nopenclaw gateway restart\n",[111,2697,2698,2706,2729,2740,2749],{"__ignoreMap":109},[114,2699,2700,2702,2704],{"class":116,"line":117},[114,2701,121],{"class":120},[114,2703,263],{"class":140},[114,2705,1819],{"class":140},[114,2707,2708,2711,2714,2717,2720,2723,2726],{"class":116,"line":147},[114,2709,2710],{"class":120},"rm",[114,2712,2713],{"class":124}," -f",[114,2715,2716],{"class":140}," \"${",[114,2718,2719],{"class":1314},"TMPDIR",[114,2721,2722],{"class":1307},":-/",[114,2724,2725],{"class":1314},"tmp",[114,2727,2728],{"class":140},"}/openclaw/managed-update-handoffs.sqlite\"\n",[114,2730,2731,2733,2735,2737],{"class":116,"line":1001},[114,2732,1824],{"class":120},[114,2734,1827],{"class":140},[114,2736,1830],{"class":124},[114,2738,2739],{"class":140}," openclaw@2026.9.4\n",[114,2741,2742,2744,2746],{"class":116,"line":1509},[114,2743,121],{"class":120},[114,2745,253],{"class":140},[114,2747,2748],{"class":124}," --non-interactive\n",[114,2750,2751,2753,2755],{"class":116,"line":1732},[114,2752,121],{"class":120},[114,2754,263],{"class":140},[114,2756,266],{"class":140},[15,2758,2759,2760,2763],{},"With the stale store gone, ",[111,2761,2762],{},"openclaw doctor --non-interactive"," exits 0 and the Gateway comes up on 2026.9.4. Take the config copy from the rollback section below before you start, because if you have already been through a failed managed update you may be in the mismatched-schema state and a clean reinstall is the way out of it, not a repair pass.",[15,2765,2766,2767,2770],{},"If your update fails earlier than this, check issue #146887 as well: it documents a 2026.9.3 → 2026.9.4 update dying in four separate stages, starting with a stdio MCP server that misses its 30-second initialize window (",[111,2768,2769],{},"MCP server \"\u003Cstdio-mcp>\" timed out: did not complete initialize within 30s",") and takes the candidate Doctor down with an unhandled rejection, then a lint check that was a warning in 2026.9.3 and is a hard upgrade gate in 2026.9.4. Removing the stdio MCP server long enough to get through the rehearsal is the documented way past the first stage. Issue #145252 is the umbrella tracker for the whole 2026.9.3 / 2026.9.4 update and recovery cluster.",[15,2772,2773],{},[202,2774],{"alt":2775,"src":2776},"Nine log lines, nine first moves: a two-column table matching each log signature to its first action, from ERR_MODULE_NOT_FOUND to a missing supervisor service.","/img/blog/openclaw-gateway-wont-start-after-update-nine-log-lines.jpg",[28,2778,2780],{"id":2779},"how-to-roll-back-without-making-it-worse","How to roll back without making it worse",[15,2782,2783],{},"Rollback is fine. Rolling back badly causes sections 3 and 7. The order that works:",[1338,2785,2786,2789,2792,2797,2800],{},[172,2787,2788],{},"Stop the service first, on every platform.",[172,2790,2791],{},"Install the previous version with an explicit pin.",[172,2793,416,2794,2796],{},[111,2795,275],{}," after the downgrade so it strips config the newer version wrote.",[172,2798,2799],{},"Start the service.",[172,2801,416,2802,2804],{},[111,2803,2296],{}," and kill any client still pointing at the newer install.",[15,2806,2807],{},"And before the next update, take the backup that makes every section above survivable. Three commands, thirty seconds:",[104,2809,2811],{"className":106,"code":2810,"language":108,"meta":109,"style":109},"cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.$(date +%F)\ncp -r ~/.openclaw/state ~/.openclaw/state.$(date +%F)\nopenclaw --version > ~/.openclaw/last-known-good.txt\n",[111,2812,2813,2836,2857],{"__ignoreMap":109},[114,2814,2815,2818,2821,2824,2827,2830,2833],{"class":116,"line":117},[114,2816,2817],{"class":120},"cp",[114,2819,2820],{"class":140}," ~/.openclaw/openclaw.json",[114,2822,2823],{"class":140}," ~/.openclaw/openclaw.json.",[114,2825,2826],{"class":1314},"$(",[114,2828,2829],{"class":120},"date",[114,2831,2832],{"class":140}," +%F",[114,2834,2835],{"class":1314},")\n",[114,2837,2838,2840,2843,2846,2849,2851,2853,2855],{"class":116,"line":147},[114,2839,2817],{"class":120},[114,2841,2842],{"class":124}," -r",[114,2844,2845],{"class":140}," ~/.openclaw/state",[114,2847,2848],{"class":140}," ~/.openclaw/state.",[114,2850,2826],{"class":1314},[114,2852,2829],{"class":120},[114,2854,2832],{"class":140},[114,2856,2835],{"class":1314},[114,2858,2859,2861,2863,2866],{"class":116,"line":1001},[114,2860,121],{"class":120},[114,2862,1496],{"class":124},[114,2864,2865],{"class":1307}," >",[114,2867,2868],{"class":140}," ~/.openclaw/last-known-good.txt\n",[15,2870,2871,2872,2875,2876,2879,2880,2883,2884,2887],{},"That last line is the one everyone skips and then needs at 2am. Our ",[229,2873,2874],{"href":236},"safe update process"," covers the full routine and the four checks worth running afterwards. Stop the Gateway before copying ",[111,2877,2878],{},"state/",", since a raw copy of a live SQLite database can be torn; ",[111,2881,2882],{},"openclaw backup create --verify"," is safe either way, and the ",[229,2885,2886],{"href":628},"backup and restore guide"," walks through it.",[15,2889,2890,2891,2894,2895,2897],{},"Take that config copy ",[503,2892,2893],{},"before"," you run ",[111,2896,1763],{},", not after. Users report the repair path pruning config keys it does not recognise, occasionally taking provider credentials parked in a field the current schema no longer knows about. The official doctor documentation does not describe this behaviour either way, so treat it as reported rather than specified, and keep the copy you took thirty seconds ago.",[15,2899,2900,2901,2903],{},"Then read the release notes for defaults that changed (2026.9.2 flipped two, covered in the ",[229,2902,1522],{"href":231},"), and update at a time when you can afford ten minutes of the Gateway being down. If you run agents for other people, \"update on Friday at 6pm\" is how you meet section 5 on a Saturday.",[15,2905,2906,2909],{},[19,2907,2908],{},"On which version to land on:"," this has not improved. ClawStat.us rated 2026.9.3 \"skip\" on 23 credible blocking issues, and its 15 September 2026 assessment gives 2026.9.4 the same verdict on 27 — \"none widespread,\" but the headline problem is the upgrade path from section 10 rather than a runtime bug, and there is no pre-release staging the fix. Its recommendation is still 2026.9.1: twelve days in the field, eleven credible known issues, none widespread. If you are on 9.1 and stable, staying there is a defensible choice this cycle rather than a failure to keep up.",[15,2911,2912],{},"We built BetterClaw, a no-code AI agent platform, because we hit almost every one of these on our own Gateways over the first six months. Updates are staged, the service is stopped and restored around them, config is migrated before restart, and if a release breaks your agent it rolls back automatically. Free plan, bring your own keys.",[28,2914,2916],{"id":2915},"what-the-ten-have-in-common","What the ten have in common",[15,2918,2919],{},"Look at them again and it's really three problems wearing ten coats. Files on disk don't match the version the Gateway thinks it is (1, 2, 6, 8). State or config on disk doesn't match the schema the Gateway expects (3, 4's rollback path, 9, and 10 in its purest form — a single leftover row written by an older updater). Or the process is fine and something around it isn't: memory (5), a stale client (7), a missing supervisor (9).",[15,2921,2922,2923,2925,2926,2928],{},"That's why the ladder works so often. ",[111,2924,1763],{}," reconciles config drift, ",[111,2927,2263],{}," reconciles the supervisor, and a clean pinned install reconciles the files. When you know which of the three you have, the fix is rarely more than four commands. When you don't, you end up deleting things at 2am. Read the log line first.",[15,2930,2931,2932,390,2935,238],{},"If any of this resonated, give BetterClaw a try. Free plan with 1 agent and 100 credits a month, bring your own API keys, no inference markup. Pro is $49 a month for 5 agents. 200+ verified skills and updates you don't have to babysit. ",[229,2933,1543],{"href":386,"rel":2934},[388],[229,2936,1546],{"href":393},[28,2938,398],{"id":397},[553,2940,2942],{"id":2941},"what-does-it-mean-when-the-openclaw-gateway-wont-start-after-an-update","What does it mean when the OpenClaw gateway won't start after an update?",[15,2944,2945,2946,2023,2948,2950],{},"It almost always means one of three things: the installed files don't match the version (an incomplete npm install, or an update that ran while the old process still held the files), the config on disk no longer validates against the new schema, or something around the process failed such as memory, a stale client, or a missing supervisor entry. The log line identifies which; ",[111,2947,275],{},[111,2949,343],{}," resolves a large share of the config and supervisor cases.",[553,2952,2954],{"id":2953},"how-does-rolling-back-openclaw-compare-to-reinstalling-the-current-version","How does rolling back OpenClaw compare to reinstalling the current version?",[15,2956,2957,2958,2960,2961,2964],{},"Reinstall first if the log shows a missing module or an incomplete tree, since that's usually a bad install rather than a bad release. Roll back when the failure is a version-specific crash loop (an unhandled rejection from a subsystem, for example) that the previous version didn't have. After any rollback, run ",[111,2959,275],{}," to strip config keys the newer version wrote, and check ",[111,2962,2963],{},"gateway status --deep"," for stale clients causing protocol mismatch.",[553,2966,2968],{"id":2967},"why-does-openclaw-202694-say-existing-managed-handoff-lease-is-incompatible","Why does OpenClaw 2026.9.4 say \"existing managed handoff lease is incompatible\"?",[15,2970,2971,2972,2975,2976,2978,2979,2982,2983,2985],{},"Because 2026.9.4 shipped without PR #144208, which merged to main on 10 September 2026 after the release branch was cut. Every config write on 2026.9.4 scans the machine-global handoff lease store and throws on any row it cannot parse, and older updaters wrote ",[111,2973,2974],{},"version: 1"," rows that the 2026.9.4 schema (versions 2 and 3 only) rejects. That breaks ",[111,2977,2675],{},", Doctor repairs and plugin convergence on any host that has updated before. Stop the Gateway, delete ",[111,2980,2981],{},"\u003Ctmp>/openclaw/managed-update-handoffs.sqlite",", install 2026.9.4 directly rather than through the managed update, then run ",[111,2984,2762],{},". It is tracked as issue #144742 and is still open.",[553,2987,2989],{"id":2988},"how-do-i-find-the-openclaw-gateway-logs-when-it-wont-stay-running","How do I find the OpenClaw gateway logs when it won't stay running?",[15,2991,2992,2993,2995,2996,1749,2998,3000,3001,3003,3004,3007],{},"Use ",[111,2994,1744],{}," if the Gateway runs at all. Otherwise read the files directly: ",[111,2997,1748],{},[111,2999,1752],{}," for a macOS LaunchAgent install, and ",[111,3002,1756],{}," on Linux systemd. For a suspected OOM loop, ",[111,3005,3006],{},"dmesg -T | grep -i \"killed process\""," is the confirming signal.",[553,3009,3011],{"id":3010},"is-it-worth-running-openclaw-update-on-a-production-gateway","Is it worth running openclaw update on a production Gateway?",[15,3013,3014,3015,3017],{},"Yes, but not casually. Stop the service before updating on macOS (the update has historically run while the LaunchAgent held files open), back up ",[111,3016,580],{}," and the state directory, read the release notes for changed defaults, and update when a ten-minute outage is acceptable. Pin the previous version's number somewhere you can find it at 2am.",[553,3019,3021],{"id":3020},"is-openclaw-doctor-fix-safe-to-run-when-the-gateway-is-down","Is openclaw doctor --fix safe to run when the gateway is down?",[15,3023,3024,3025,3028,3029,3031,3032,3034],{},"Yes; it's the fourth rung of the project's own post-update ladder and is designed to run against a stopped Gateway. It migrates config drift, cleans version-gated plugin entries after a rollback, rewrites stale supervisor metadata such as a changed port, and reports the last gateway error from the logs. It won't repair an incomplete install; for missing ",[111,3026,3027],{},"dist/"," files, reinstall or pin a version instead. Two caveats the documentation does not cover: users report it pruning config keys it does not recognise, so copy ",[111,3030,580],{}," before running it, and it does not reconcile a legacy ",[111,3033,2373],{}," that conflicts with the shared SQLite plugin index, which is the one crash loop that repeat passes will never clear.",[451,3036,1624],{},{"title":109,"searchDepth":147,"depth":147,"links":3038},[3039,3040,3041,3042,3043,3044,3045,3046,3047,3048,3049,3050,3051,3052],{"id":1683,"depth":147,"text":1684},{"id":1779,"depth":147,"text":1780},{"id":1871,"depth":147,"text":1872},{"id":1936,"depth":147,"text":1937},{"id":2013,"depth":147,"text":2014},{"id":2085,"depth":147,"text":2086},{"id":2174,"depth":147,"text":2175},{"id":2272,"depth":147,"text":2273},{"id":2300,"depth":147,"text":2301},{"id":2528,"depth":147,"text":2529},{"id":2625,"depth":147,"text":2626},{"id":2779,"depth":147,"text":2780},{"id":2915,"depth":147,"text":2916},{"id":397,"depth":147,"text":398,"children":3053},[3054,3055,3056,3057,3058,3059],{"id":2941,"depth":1001,"text":2942},{"id":2953,"depth":1001,"text":2954},{"id":2967,"depth":1001,"text":2968},{"id":2988,"depth":1001,"text":2989},{"id":3010,"depth":1001,"text":3011},{"id":3020,"depth":1001,"text":3021},"2026-09-10","OpenClaw gateway won't start after updating? Ten post-update failures matched to their exact log lines, with the fix and safe rollback for each.","/img/blog/openclaw-gateway-wont-start-after-update.jpg",{},"15 min read",{"title":1662,"description":3061},"OpenClaw Gateway Won't Start After Update: Fixes","blog/openclaw-gateway-wont-start-after-update",[3069,3070,3071,3072,3073,1655,3074,3075,3076,3077],"openclaw gateway won't start","openclaw gateway not starting after update","openclaw crash loop","openclaw err_module_not_found","openclaw doctor fix","openclaw port 18789 in use","openclaw update failed","openclaw 2026.9.4 config write failed","managed handoff lease is incompatible","2026-09-16","wJZFBu3t4p0QV8c74KeiAmAsAnF_s7pRO8Os8Zrqk50",1790752234752]