Troubleshooting and FAQ

Where are the logs? All under ~/.klaus/: the desktop app's diagnostics go to electron-host.log, one JSON object per line, found by their kind field — scheduled tasks are cron, dreaming and memory maintenance are memory-maintenance; MCP diagnostics and channel traffic are in logs/. Attaching the relevant snippets when reporting an issue helps with diagnosis (in-app feedback includes session information automatically, so you do not need to paste it yourself).

Where is my data stored? Sessions, settings, memory, and other local data all live under the ~/.klaus/ directory.

A connector will not open / keeps showing that authorization is needed? Complete the corresponding authorization first, in "Settings → System Permissions" or in macOS System Settings, then restart Klaus — it does not take effect without a restart.

A scheduled task did not fire? Check in order: whether the task is enabled; whether the next run time matches your expectation (mind the time zone); the run history in the task's detail view, and the entries with kind cron in ~/.klaus/electron-host.log around that time. A single run times out after 5 minutes by default, but the task's own "timeout seconds" value is honored (capped at 24 hours), so long-running tasks need that value raised. If the process exits mid-run (an update restart, a crash), records stuck in "running" are marked as failed on the next launch.

Klaus never dreams? Automatic dreaming is off by default — turn it on under "Settings → Dreams" first. After that, two conditions must both hold for a dream to run: at least 24 hours since the last dream, and at least 5 new sessions accumulated. Don't want to wait? Trigger one manually on the memory page with "Dream now": the manual trigger ignores both thresholds, but it still requires that switch to be on, and at least one session must have completed a turn since this launch. (By the way, the "Auto-record" switch on the same page is also off by default; without it Klaus will not jot things down on its own.)

Hooks are written but never run? The two most common causes: an entry with a misspelled event name is dropped outright (no error), or the hook declaration has not been trusted yet in "Settings → Hooks" — new declarations and declarations whose content changed are never executed; see Hooks.

Why did my MCP / project configuration change not take effect? Two cases: changes made inside the app (installing a skill from the marketplace, enabling or disabling a plugin, clicking trust on the hooks page) mark already-open sessions as stale, and the new values are rebuilt automatically between turns — no need to reopen. But edits you make to files on disk in your own editor do not work that way — Klaus does not watch those directories, so you have to start a new session for them to be read. See How Extensions Are Loaded.

Can Klaus change settings, create tasks, and install skills on its own? Yes — just ask. Read-only operations it does directly; irreversible actions prompt you first, and during a scheduled task run no irreversible changes are made at all. See Letting Klaus Operate Klaus.

Does Klaus know about itself? This manual ships with the app and Klaus can search it directly, so questions about product behavior, what a switch means, or internal mechanics can all be asked straight up.

How do I report an issue? Each session's ⋯ menu has "Report an issue", which attaches session context automatically; or email support@klaus-ai.cn. The idea (suggestion) window has no in-app entry — just tell Klaus and it will submit on your behalf; see Feedback and Suggestions.