What this page covers: locating errors, not fixing every failure class
Searches for “OpeClaw logs” or “OpeClaw error diagnosis” usually mean you already see a red message, dialog, or failed task—but not where logs live, which lines matter, or what to gather before asking for help.
This article covers: collecting logs via the current-build entry points, reading time-aligned key lines, a self-check list, and redaction before sharing. Never opens → won’t-open. Opens but stuck on loading → slow-startup. 401/429 and quota → API key. Corporate proxy/TLS → proxy guide.
It does not invent specific log filenames, log-level toggles, or promises that “submitting gets a reply.” Menu labels and folder names follow your current build. Installers → Download. Scenario boundaries → FAQ.
Split first: not every red line belongs on “read the logs”
Logs are evidence, not a cure-all. If the client never starts, crashes instantly, or is killed by antivirus/Gatekeeper, use won’t-open first—logs may never be written fully.
If a process exists and you eventually reach the UI but loading takes forever, compare against the slow-startup guide (login items, Skills, local-model cold start) before treating logs as the main path.
When the UI or response already says 401, invalid key, 429, or quota exceeded, use the API key guide first; retrying the same key only noisy-fills the log. HTTPS interception or untrusted certificates → proxy / model-connection guide.
- No process / instant exit → won’t-open.
- Process present, stuck loading but eventually opens → slow-startup.
- Clear 401/429 → API key guide.
- Proxy/TLS errors → proxy guide; otherwise collect evidence here.
Where logs live: prefer the in-app entry, then user-data folders
Prefer Settings, Help, or About for “Open logs,” “Export diagnostics,” or “Reveal logs”—that path tracks version differences best.
If there is no entry, look near the user-data folder: common examples are `%AppData%/OpeClaw` on Windows (paste into Explorer) and `~/Library/Application Support/OpeClaw` on macOS. Whether a child folder is named logs, diagnostics, or something else follows your machine’s current build—do not assume a fixed filename.
On managed PCs that block AppData / Application Support, follow IT policy; do not disable security tools to copy files. Note the About version so you can compare with the download page.
How to read: align the clock, catch status codes and the first stack
Reproduce once, note the approximate time, then open the newest log and read only that window. Reading the entire file top-to-bottom is the slowest approach.
Search first for ERROR, Exception, Failed, timeout, ECONNREFUSED, permission denied, and HTTP status codes (401, 403, 429, 5xx). The useful part is usually the first real error plus the next few reason lines—not a long chain of follow-on warnings.
If the same window shows both a model-call failure and a local path denial, separate cloud response errors from local permissions before jumping to API key, proxy, or workspace guides—this page does not replace those topic articles.
Before you ask for help: self-check and redaction
Self-check at least once: About version/platform vs the download page; whether it is actually won’t-open / slow-startup / 401 / proxy (see splits above); whether you just changed a key, proxy, or Skill; and whether the shortest reproduction is clear (action → expected → actual).
Before sharing logs, redact API keys, Bearer tokens, and cookies; blur local usernames and absolute paths; drop unrelated chat transcripts. Keep only the time-aligned error snippet.
That packet helps your own notes and whichever help channel you choose. This site does not promise official tickets, SLAs, or “submit and someone will reply.”
Error-location table (no new claims)
This table only restates the splits above. It does not change “evidence here, topic failures on their own guides.”
| Symptom | Safer action | Common mistake |
|---|---|---|
| Do not know where logs are | Use Settings/Help log or diagnostics entry first | Copying outdated hard-coded paths |
| Red text, unclear class | Reproduce; clip time-aligned ERROR only | Sending full unredacted logs |
| Double-click does nothing | Won’t-open guide | Hunting logs that were never written |
| Stuck loading but eventually opens | Slow-startup guide | Treating slow launch as a mystery error |
| 401 / 429 | API key guide | Retrying the same key against noisy logs |
| Proxy / certificate errors | Proxy guide | Only rotating keys while ignoring TLS |
Folder and menu labels follow the current client; this page does not invent unpublished log-level toggles.
Logs & error diagnosis FAQ
Where are OpeClaw logs usually stored?
Start from any in-app “open logs / diagnostics folder” control in Settings or Help. If there is none, look near the user-data folder (often %AppData%/OpeClaw on Windows, ~/Library/Application Support/OpeClaw on macOS). Subfolder and file names vary by build—follow your current version, not a third-party hard-coded path.
Which log lines should I read first?
Align to the time you reproduced the issue, then look for ERROR / Exception / Failed / timeout and nearby HTTP status codes or “permission denied” hints. Do not skim the whole file; capture a few dozen lines before and after the first real error.
What should I prepare before asking for help?
Have ready: About-page version and platform, reproduction steps (what you clicked, expected vs actual), a redacted log snippet (API keys and local paths removed), and which split you already ruled out (e.g. not 401, not a total won’t-open). This page does not promise any official support channel.
How is this different from slow startup, won’t-open, or 401?
No process / instant exit → won’t-open. Process exists but loading stalls → slow-startup guide. Clear 401/429 → API key guide. Proxy/TLS issues → proxy guide. This page only covers how to collect logs, read key lines, and self-check before asking for help.
Use this with an OpeClaw workflow
Check the current OpeClaw download status first, then save this guide as part of your setup, review, or troubleshooting workflow.