Personal troubleshooting
The app or Engine does not start
- Confirm you installed the package for the correct platform and architecture.
- Restart using the platform's normal app or host command; do not launch internal server files directly.
- On macOS, use the installed CLI:
~/clawuno/bin/clawuno status
~/clawuno/bin/clawuno doctor --check
~/clawuno/bin/clawuno doctor --report
- Keep the generated diagnostic archive. On Linux Docker, collect status and recent logs instead; its host manager does not provide
doctoror generate this archive:
sudo clawuno status
sudo clawuno logs
For a named instance, add --instance NAME to each Linux command. Review all diagnostics before sharing because logs can contain filenames, hostnames or service endpoints.
On Windows Desktop, first quit and reopen the app. If the UI opens but the Engine does not, keep %LOCALAPPDATA%\Clawuno and %USERPROFILE%\clawuno intact and collect the Desktop and Engine diagnostics before reinstalling.
On macOS 0.8.4.1 or earlier, an update or the next launch may stop with Cannot inspect process and leave the Engine stopped, even after you reopen the app. Quit Clawuno from its menu bar icon, then install the current DMG from the official download page over the existing app. Version 0.8.5 and later complete the interrupted update on first launch and keep the data in ~/clawuno. Do not delete ~/clawuno or reset the app's preferences.
If an update from macOS 0.8.4.1 or earlier shows "Could not safely prepare the local Engine for updating. The update was not installed.", your current version keeps running and your data is unchanged. Choose Clawuno → Check for Updates again; a second attempt normally succeeds. If it keeps failing, install the current DMG over the app as described above.
The starting screen appears temporarily
Wait while the Engine is busy. A slow backup or other host operation can delay requests without meaning the process has stopped. Do not repeatedly terminate the app while an operation is still progressing.
The page looks stuck or out of date
In the desktop app, choose View → Reload Page on macOS (⌘R), or View → Reload page on Windows (Ctrl+R or F5). Only the current window reloads, and it stays on the same page. When a Browser Tab has focus, the shortcut does not reload the Clawuno page; use the menu instead.
Reloading discards text you have not sent and file edits you have not saved, so save them first. If the Engine cannot be reached, the current page stays open and shows a connection notice; reload again once the Engine is back. The command is unavailable on the starting screen and on the connection page, which has its own Retry.
Sign-in fails
Confirm the URL belongs to the intended installation and that browser cookies are allowed. On servers, use the same public origin consistently; switching between IP addresses and hostnames creates separate cookie origins.
If an administrator forgot the password, use operating-system access to create a single-use reset URL valid for 15 minutes:
- macOS:
~/clawuno/bin/clawuno admin reset-token --new --email ADMIN_EMAIL - Windows Desktop: quit Clawuno, open PowerShell as the Windows user who installed it, and run:
$engine = "$env:LOCALAPPDATA\ClawunoDesktop\current\engine"
$env:DATA_ROOT = "$env:USERPROFILE\clawuno\data"
& "$engine\runtime\node.exe" "$engine\bin\admin-cli.js" reset-token --new --email "ADMIN_EMAIL"
Remove-Item Env:DATA_ROOT
Open the printed URL on the same trusted computer and set a new password. The command does not reveal the old password. Never post the reset token in Chat or a public support ticket.
A model test fails
Check the provider, endpoint, model ID and credential. Confirm the host can reach that endpoint. Cloud-provider rate limits and account permissions are separate from Clawuno health.
Office preview or Engine Browser is unavailable
Open System Settings → Health and inspect managed runtime status. Use the provided repair action for the current generation. Opening a document or Browser tab does not download a missing runtime on demand.
System cache is preparing or reports incomplete data
Cache preparation runs quietly in the background, without a cache notice in your conversation list; you can still enter Clawuno and open settings. An opened Workspace can show readable conversations while the cache is unavailable. Records that cannot be verified are left out of lists and statistics, which stay available; System Settings → Health → System Cache notes that some records need attention. While the cache is still being prepared, statistics show as preparing rather than zero.
Administrators can use System Settings → Health → System Cache to check or rebuild it. This does not change original conversations or permissions. If the warning persists, keep your data and collect diagnostics; rebuilding repeatedly cannot repair damaged source files. Damaged historical records do not block unrelated new runs. Execution limits use current running tasks, not historical status or cache completeness. A damaged conversation may still be unavailable, and a failure to safely reserve execution resources is reported as a task that did not start, not a disconnected conversation.
Ask for help
Include the exact Clawuno version, platform, install type, time of failure, action that failed, and the diagnostic report. Do not send API keys, passwords, installation credentials or complete private documents.