[{"data":1,"prerenderedAt":765},["ShallowReactive",2],{"help-category-\u002Ftroubleshooting\u002Fgateway-fails-to-start":3,"help-article-\u002Ftroubleshooting\u002Fgateway-fails-to-start":4,"related-articles-\u002Ftroubleshooting\u002Fgateway-fails-to-start":267},[],{"id":5,"title":6,"body":7,"category":253,"description":254,"draft":255,"extension":256,"meta":257,"navigation":258,"order":245,"path":259,"relatedArticles":260,"seo":261,"slug":262,"stem":263,"updatedAt":264,"__hash__":265,"excerpt":254,"searchText":266},"help\u002Fhelp\u002Ftroubleshooting\u002F02.gateway-fails-to-start.md","Gateway fails to start",{"type":8,"value":9,"toc":243},"minimark",[10,44,49,55,60,97,101,104,108,128,132,135,139,166,170,173,177,202,206,209,213,232,236],[11,12,13,14,18,19,22,23,26,27,31,32,35,36,39,40,43],"p",{},"If your gateway shows a red ",[15,16,17],"strong",{},"Error"," or ",[15,20,21],{},"Stopped"," status in ",[15,24,25],{},"Settings > Gateway"," and won't start, a port conflict is the most common cause. The gateway port is configured in your OpenClaw configuration file (",[28,29,30],"code",{},"~\u002F.openclaw\u002Fopenclaw.json",") — if port ",[28,33,34],{},"18789"," is taken, update the ",[28,37,38],{},"port"," value there, then click ",[15,41,42],{},"Restart gateway",". If that doesn't help, work through the causes below.",[45,46,48],"h2",{"id":47},"port-conflict","Port conflict",[11,50,51,52,54],{},"Another process on your machine is already using port ",[28,53,34],{}," (the default gateway port). The gateway cannot bind to a port that's taken.",[11,56,57],{},[15,58,59],{},"To fix:",[61,62,63,70,81,90],"ol",{},[64,65,66,67,69],"li",{},"Open ",[28,68,30],{}," in a text editor.",[64,71,72,73,76,77,80],{},"Change the ",[28,74,75],{},"\"port\""," value to an unused port (e.g. ",[28,78,79],{},"18790",").",[64,82,83,84,86,87,89],{},"Save the file and click ",[15,85,42],{}," in ",[15,88,25],{},".",[64,91,92,93,96],{},"If you're on macOS or Linux and want to identify the conflicting process first, run ",[28,94,95],{},"lsof -i :18789"," in your terminal.",[45,98,100],{"id":99},"missing-or-corrupt-openclaw-binary","Missing or corrupt OpenClaw binary",[11,102,103],{},"The OpenClaw binary was deleted, moved, or never fully downloaded. Without it, the gateway cannot run.",[11,105,106],{},[15,107,59],{},[61,109,110,121],{},[64,111,112,113,120],{},"Reinstall the MultiClaw desktop app from ",[114,115,119],"a",{"href":116,"rel":117},"https:\u002F\u002Fmulticlaw.io\u002Fdownload",[118],"nofollow","multiclaw.io\u002Fdownload"," — this restores the OpenClaw binary.",[64,122,123,124,86,126,89],{},"Once reinstalled, click ",[15,125,42],{},[15,127,25],{},[45,129,131],{"id":130},"empty-or-invalid-workspace-token","Empty or invalid workspace token",[11,133,134],{},"Your gateway token was cleared — this can happen after a failed sign-in or an app reset. The gateway won't start without a valid token.",[11,136,137],{},[15,138,59],{},[61,140,141,151,157,160],{},[64,142,66,143,146,147,150],{},[15,144,145],{},"Settings > General"," and scroll to the ",[15,148,149],{},"Account"," card.",[64,152,153,154,89],{},"Click ",[15,155,156],{},"Log out",[64,158,159],{},"Sign back in with your account credentials.",[64,161,162,163,165],{},"Your token is regenerated automatically. Click ",[15,164,42],{}," once signed in.",[45,167,169],{"id":168},"binary-not-executable-macos-and-linux","Binary not executable (macOS and Linux)",[11,171,172],{},"The OpenClaw binary exists but does not have execute permissions. This often happens after a manual file move or a filesystem restore.",[11,174,175],{},[15,176,59],{},[61,178,179,190,196],{},[64,180,181,182,185,186,189],{},"The OpenClaw binary is located at ",[28,183,184],{},"~\u002F.openclaw\u002Fbin\u002Fopenclaw"," on macOS and Linux (or ",[28,187,188],{},"%APPDATA%\\OpenClaw\\bin\\openclaw.exe"," on Windows).",[64,191,192,193,89],{},"In your terminal, run ",[28,194,195],{},"chmod +x ~\u002F.openclaw\u002Fbin\u002Fopenclaw",[64,197,153,198,86,200,89],{},[15,199,42],{},[15,201,25],{},[45,203,205],{"id":204},"data-directory-inaccessible","Data directory inaccessible",[11,207,208],{},"The OpenClaw data directory no longer exists or your user account cannot write to it. The gateway needs a writable directory to store its data.",[11,210,211],{},[15,212,59],{},[61,214,215,219,226],{},[64,216,66,217,69],{},[28,218,30],{},[64,220,221,222,225],{},"Update the ",[28,223,224],{},"\"data_dir\""," value to a folder that exists and that you have write access to.",[64,227,153,228,86,230,89],{},[15,229,42],{},[15,231,25],{},[45,233,235],{"id":234},"still-not-working","Still not working?",[11,237,238,239,242],{},"Check the gateway log at ",[28,240,241],{},"~\u002F.openclaw\u002Flogs\u002Fgateway.log"," — it will usually identify the exact failure line.",{"title":244,"searchDepth":245,"depth":245,"links":246},"",2,[247,248,249,250,251,252],{"id":47,"depth":245,"text":48},{"id":99,"depth":245,"text":100},{"id":130,"depth":245,"text":131},{"id":168,"depth":245,"text":169},{"id":204,"depth":245,"text":205},{"id":234,"depth":245,"text":235},"troubleshooting","Diagnose and fix port conflicts, missing binaries, token errors, and permission problems.",false,"md",{},true,"\u002Ftroubleshooting\u002Fgateway-fails-to-start",[],{"title":6,"description":254},"gateway-fails-to-start","help\u002Ftroubleshooting\u002F02.gateway-fails-to-start","2026-03-30","_0wciXQlb9TxhMmXBMEySTf8zKPz2-_ue4yZEGoHNvI","Gateway fails to start Diagnose and fix port conflicts, missing binaries, token errors, and permission problems.",[268,403,586],{"id":269,"title":270,"body":271,"category":253,"description":393,"draft":255,"extension":256,"meta":394,"navigation":258,"order":395,"path":396,"relatedArticles":397,"seo":398,"slug":399,"stem":400,"updatedAt":264,"__hash__":401,"excerpt":393,"searchText":402},"help\u002Fhelp\u002Ftroubleshooting\u002F01.agent-shows-disconnected.md","Agent shows 'Disconnected'",{"type":8,"value":272,"toc":384},[273,287,291,300,304,307,311,319,323,332,336,350,354,362,366,374],[11,274,275,276,279,280,282,283,286],{},"The ",[15,277,278],{},"Disconnected"," badge appears when the local OpenClaw gateway cannot reach MultiClaw Cloud. In most cases, the gateway has stopped — open ",[15,281,25],{}," and click ",[15,284,285],{},"Start gateway"," to fix it.",[45,288,290],{"id":289},"gateway-is-not-running","Gateway is not running",[11,292,293,294,296,297,299],{},"This is the most common cause. Go to ",[15,295,25],{}," and check the gateway status. If it shows as stopped, click ",[15,298,285],{}," and wait a few seconds for the agent status to update.",[45,301,303],{"id":302},"internet-connection-is-unavailable","Internet connection is unavailable",[11,305,306],{},"The gateway requires internet access to reach MultiClaw Cloud. Verify your machine can load a webpage. If your network is down, the agent will reconnect automatically once connectivity is restored.",[45,308,310],{"id":309},"multiclaw-cloud-is-experiencing-an-outage","MultiClaw Cloud is experiencing an outage",[11,312,313,314,318],{},"If your gateway is running and you have internet access, check ",[114,315,316],{"href":316,"rel":317},"https:\u002F\u002Fstatus.multiclaw.io",[118]," for any active incidents. No action is needed on your end — the gateway will reconnect once the service recovers.",[45,320,322],{"id":321},"workspace-session-has-expired","Workspace session has expired",[11,324,325,326,328,329,331],{},"Your session can expire after a period of inactivity. Go to ",[15,327,145],{},", scroll to the ",[15,330,149],{}," card, and sign in again. The gateway will re-authenticate and the agent should show as connected within a few seconds.",[45,333,335],{"id":334},"firewall-or-proxy-blocking-the-connection","Firewall or proxy blocking the connection",[11,337,338,339,342,343,346,347,89],{},"Some corporate firewalls block outbound WebSocket connections. The gateway connects to MultiClaw Cloud over port ",[15,340,341],{},"443"," using the ",[15,344,345],{},"WSS"," protocol. Ask your IT administrator to allow outbound WSS traffic on port 443 to ",[28,348,349],{},"*.multiclaw.io",[45,351,353],{"id":352},"auth-token-has-expired-or-been-revoked","Auth token has expired or been revoked",[11,355,356,357,328,359,361],{},"If signing in again does not help, your local auth token may be corrupted or revoked. Go to ",[15,358,145],{},[15,360,149],{}," card, sign out completely, then sign back in. This replaces the stored token and typically resolves the issue.",[45,363,365],{"id":364},"gateway-is-running-but-agent-stays-disconnected","Gateway is running but agent stays disconnected",[11,367,368,369,282,371,373],{},"Transient WebSocket errors can leave the gateway in a stuck state. Go to ",[15,370,25],{},[15,372,42],{},". The gateway reconnects with exponential back-off — waiting 30–60 seconds after a brief network interruption often resolves it without a manual restart.",[375,376,378],"callout",{"type":377},"tip",[11,379,380,381,383],{},"If none of the steps above work, check the gateway log at ",[28,382,241],{}," for error messages that may point to the cause.",{"title":244,"searchDepth":245,"depth":245,"links":385},[386,387,388,389,390,391,392],{"id":289,"depth":245,"text":290},{"id":302,"depth":245,"text":303},{"id":309,"depth":245,"text":310},{"id":321,"depth":245,"text":322},{"id":334,"depth":245,"text":335},{"id":352,"depth":245,"text":353},{"id":364,"depth":245,"text":365},"Fix a disconnected agent status caused by gateway, network, session, or firewall issues.",{},1,"\u002Ftroubleshooting\u002Fagent-shows-disconnected",[],{"title":270,"description":393},"agent-shows-disconnected","help\u002Ftroubleshooting\u002F01.agent-shows-disconnected","9zuPiU2Ea9ivpf9-W_pFwN6PdgHplZxnykc7tldh_5k","Agent shows 'Disconnected' Fix a disconnected agent status caused by gateway, network, session, or firewall issues.",{"id":404,"title":405,"body":406,"category":253,"description":576,"draft":255,"extension":256,"meta":577,"navigation":258,"order":578,"path":579,"relatedArticles":580,"seo":581,"slug":582,"stem":583,"updatedAt":264,"__hash__":584,"excerpt":576,"searchText":585},"help\u002Fhelp\u002Ftroubleshooting\u002F03.cannot-sign-in.md","Cannot sign in",{"type":8,"value":407,"toc":568},[408,411,415,426,441,445,448,453,464,469,485,489,496,510,514,517,531,535,538,549,553,556],[11,409,410],{},"If you cannot sign in, start by checking your workspace URL — most sign-in failures are caused by using the wrong subdomain. Open your invite email and copy the URL directly from it.",[45,412,414],{"id":413},"wrong-workspace-url","Wrong workspace URL",[11,416,417,418,421,422,425],{},"Your workspace has a unique subdomain. ",[28,419,420],{},"acme.multiclaw.io"," and ",[28,423,424],{},"acme.app.multiclaw.io"," are different addresses — only one is yours.",[61,427,428,431,434],{},[64,429,430],{},"Open your original invite email.",[64,432,433],{},"Copy the workspace URL exactly as written.",[64,435,436,437,440],{},"Paste it into your browser or the Desktop app's ",[15,438,439],{},"Workspace URL"," field.",[45,442,444],{"id":443},"expired-or-invalid-session","Expired or invalid session",[11,446,447],{},"Your session token may have expired, especially after a long period of inactivity.",[11,449,450],{},[15,451,452],{},"On the web dashboard:",[61,454,455,461],{},[64,456,457,458,89],{},"Open your browser's cookie settings and clear all cookies for ",[28,459,460],{},"multiclaw.io",[64,462,463],{},"Return to your workspace URL and sign in again.",[11,465,466],{},[15,467,468],{},"On the Desktop app:",[61,470,471,478,482],{},[64,472,473,474,146,476,150],{},"Go to ",[15,475,145],{},[15,477,149],{},[64,479,153,480,89],{},[15,481,156],{},[64,483,484],{},"Sign back in with your credentials.",[45,486,488],{"id":487},"sign-in-with-multiplai-error","Sign in with Multiplai error",[11,490,491,492,495],{},"If you use ",[15,493,494],{},"Sign in with Multiplai"," and see an error, the issue is usually a session mismatch between Multiplai and MultiClaw.",[61,497,498,501,507],{},[64,499,500],{},"Sign out of both Multiplai and MultiClaw completely.",[64,502,503,504,506],{},"Return to the MultiClaw sign-in screen and click ",[15,505,494],{}," again.",[64,508,509],{},"If the error persists, try signing in with email and password instead, or contact support.",[45,511,513],{"id":512},"email-not-confirmed","Email not confirmed",[11,515,516],{},"If you signed up recently and have never signed in before, your email address may not be confirmed yet.",[61,518,519,522,525],{},[64,520,521],{},"Check your inbox and spam\u002Fjunk folder for a confirmation email from MultiClaw.",[64,523,524],{},"Click the link inside that email.",[64,526,527,528,89],{},"If the email has expired or you cannot find it, return to the sign-in screen and click ",[15,529,530],{},"Resend confirmation",[45,532,534],{"id":533},"account-locked","Account locked",[11,536,537],{},"After repeated failed sign-in attempts, access may be temporarily restricted.",[61,539,540,543],{},[64,541,542],{},"Wait a few minutes, then try again.",[64,544,545,546,89],{},"If you still cannot sign in, ask your workspace admin to check your account status in MultiClaw Cloud under ",[15,547,548],{},"Settings → Members",[45,550,552],{"id":551},"multiclaw-cloud-is-down","MultiClaw Cloud is down",[11,554,555],{},"Occasionally, sign-in fails because the service itself is unavailable.",[61,557,558,565],{},[64,559,560,561,564],{},"Visit ",[114,562,316],{"href":316,"rel":563},[118]," to check for active incidents.",[64,566,567],{},"If an incident is reported, wait for it to be resolved — no action is needed on your end.",{"title":244,"searchDepth":245,"depth":245,"links":569},[570,571,572,573,574,575],{"id":413,"depth":245,"text":414},{"id":443,"depth":245,"text":444},{"id":487,"depth":245,"text":488},{"id":512,"depth":245,"text":513},{"id":533,"depth":245,"text":534},{"id":551,"depth":245,"text":552},"Resolve sign-in failures caused by wrong workspace URL, expired sessions, SSO errors, or unconfirmed email.",{},3,"\u002Ftroubleshooting\u002Fcannot-sign-in",[],{"title":405,"description":576},"cannot-sign-in","help\u002Ftroubleshooting\u002F03.cannot-sign-in","59H6ZnK81o4O-gYFOFiVOMekfEPx496CxJfHU7S5Myw","Cannot sign in Resolve sign-in failures caused by wrong workspace URL, expired sessions, SSO errors, or unconfirmed email.",{"id":587,"title":588,"body":589,"category":253,"description":754,"draft":255,"extension":256,"meta":755,"navigation":258,"order":756,"path":757,"relatedArticles":758,"seo":759,"slug":760,"stem":761,"updatedAt":762,"__hash__":763,"excerpt":754,"searchText":764},"help\u002Fhelp\u002Ftroubleshooting\u002F04.desktop-app-wont-update.md","Desktop app won't update",{"type":8,"value":590,"toc":744},[591,602,606,620,624,631,642,646,651,663,667,670,679,683,690,699,703,706,717,721,724,733,737],[11,592,593,594,597,598,601],{},"MultiClaw checks for updates automatically and shows progress in ",[15,595,596],{},"Settings > About",". If an update fails, the fastest fix is to check your internet connection and click ",[15,599,600],{},"Check for Updates"," in Settings > About. If it still fails, one of the causes below matches your situation.",[45,603,605],{"id":604},"check-your-app-version","Check your app version",[11,607,608,609,611,612,615,616,619],{},"Before troubleshooting, confirm which version you're running. Open ",[15,610,596],{}," — the ",[15,613,614],{},"Version"," row shows the currently installed version, and the ",[15,617,618],{},"Edition"," row shows whether you're running MultiClaw Companion or Enterprise.",[45,621,623],{"id":622},"no-internet-connection","No internet connection",[11,625,626,627,630],{},"The updater contacts ",[28,628,629],{},"cdn.multiclaw.io"," to download the latest release. If your internet is down or unstable, the update fails and the About section shows an error message.",[11,632,633,636,637,282,639,641],{},[15,634,635],{},"Fix:"," Verify you have internet access, then go to ",[15,638,596],{},[15,640,600],{}," to retry.",[45,643,645],{"id":644},"firewall-blocking-the-update-url","Firewall blocking the update URL",[11,647,648,649,89],{},"Corporate firewalls sometimes block HTTPS downloads from unfamiliar domains, including ",[28,650,629],{},[11,652,653,655,656,658,659,282,661,641],{},[15,654,635],{}," Ask your IT team to allow outbound HTTPS traffic to ",[28,657,629],{},". Once allowed, go to ",[15,660,596],{},[15,662,600],{},[45,664,666],{"id":665},"not-enough-disk-space","Not enough disk space",[11,668,669],{},"The updater needs roughly 200 MB of free space to download and unpack the installer. If your disk is full, the download fails and Settings > About shows a disk space error.",[11,671,672,674,675,282,677,641],{},[15,673,635],{}," Free up at least 200 MB of disk space, then go to ",[15,676,596],{},[15,678,600],{},[45,680,682],{"id":681},"update-downloads-but-restart-fails","Update downloads but restart fails",[11,684,685,686,689],{},"If Settings > About shows ",[15,687,688],{},"Restart Now"," but clicking it doesn't complete the update, you can click it again — the app allows up to three restart attempts. After three failed attempts, the button is replaced with a message asking you to close and reopen MultiClaw manually.",[11,691,692,694,695,89],{},[15,693,635],{}," Close MultiClaw completely and reopen it. The update applies on next launch. If the problem persists, download the full installer from ",[114,696,697],{"href":697,"rel":698},"https:\u002F\u002Fdownload.multiclaw.io",[118],[45,700,702],{"id":701},"update-signature-verification-failed","Update signature verification failed",[11,704,705],{},"The updater verifies every download before installing. If the verification fails — usually because of a corrupted download — Settings > About shows a signature error.",[11,707,708,710,711,713,714,89],{},[15,709,635],{}," Click ",[15,712,600],{}," to retry the download. If the error persists, download the full installer directly from ",[114,715,697],{"href":697,"rel":716},[118],[45,718,720],{"id":719},"macos-gatekeeper-or-windows-smartscreen-blocked-the-installer","macOS Gatekeeper or Windows SmartScreen blocked the installer",[11,722,723],{},"Occasionally the OS blocks the installer because a network interruption corrupted the signature check during download. This is rare.",[11,725,726,728,729,732],{},[15,727,635],{}," Download the full installer directly from ",[114,730,697],{"href":697,"rel":731},[118]," and run it. In most cases, installing over your existing copy preserves your settings and local data. As a precaution, ensure your data is synced to a workspace before proceeding.",[45,734,736],{"id":735},"still-stuck","Still stuck?",[11,738,739,740,743],{},"Manual download is always available at ",[114,741,697],{"href":697,"rel":742},[118]," as a reliable fallback.",{"title":244,"searchDepth":245,"depth":245,"links":745},[746,747,748,749,750,751,752,753],{"id":604,"depth":245,"text":605},{"id":622,"depth":245,"text":623},{"id":644,"depth":245,"text":645},{"id":665,"depth":245,"text":666},{"id":681,"depth":245,"text":682},{"id":701,"depth":245,"text":702},{"id":719,"depth":245,"text":720},{"id":735,"depth":245,"text":736},"Fix a stuck or failing auto-updater by clearing cache or downloading the installer manually.",{},4,"\u002Ftroubleshooting\u002Fdesktop-app-wont-update",[],{"title":588,"description":754},"desktop-app-wont-update","help\u002Ftroubleshooting\u002F04.desktop-app-wont-update","2026-04-06","DK6AhqHSWcPMAQv_qOMZfrLCK_01B-3SCRaMZXdYf_4","Desktop app won't update Fix a stuck or failing auto-updater by clearing cache or downloading the installer manually.",1778463886857]