Troubleshooting & Bug Reporting

Troubleshooting & Bug Reporting

When OpenClacky misbehaves (crashes, hangs, wrong replies, tool-call errors), please get the logs based on your situation.

Launcher Shows "Service Running" but Browser Can't Open Web UI

If the launcher shows Agent Service Running but clicking "Open Agent in Browser" leads to an unreachable page, the server process itself may have encountered an error. Since you can't access the Web UI, use the tray icon to get the logs.

macOS

  1. Click the OpenClacky tray icon in the menu bar (top-right corner).
  2. Select Show Logs from the popup menu.
  3. In the log window, click the Copy Log button in the bottom-right corner to copy the full log to your clipboard.
  4. Paste the log content along with the bug report information below and submit it to the appropriate channel.

Windows

  1. Click the OpenClacky tray icon in the system tray (bottom-right corner of the taskbar — you may need to click "^" to expand hidden icons first).
  2. Select Show Logs from the popup menu.
  3. In the log window, click the Copy Log button in the bottom-right corner to copy the full log to your clipboard.
  4. Paste the log content along with the bug report information below and submit it to the appropriate channel.

Browser Can Open Web UI but Behaves Abnormally

The OpenClacky Web UI's "Download session files" action now bundles session + today's log into a single zip. You don't need to hunt for the log file by hand.

Steps:

  1. Open the OpenClacky Web UI and enter the session where the bug happened (the chat page).
  2. Look at the status bar at the bottom of the chat area — the row right above the message input shows the run state, a Session file link, working directory, model, task count, and cost.
  3. Click "Session file" and your browser will download clacky-session-xxxxxxxx.zip.

Zip contents:

clacky-session-xxxxxxxx.zip
├── session.json               # session metadata (messages, tool calls, config)
├── chunk-1.md                 # archived conversation chunks (if any)
├── chunk-2.md
├── ...
└── logs/
    └── clacky-2026-05-16.log  # today's full log

If there's no logs/ directory in the zip, today's log file simply hasn't been written yet (rare — usually only right after startup, before any tool ran). In that case, see the manual fallback below.

Manual Log Attachment (Fallback)

If you're on an older OpenClacky build whose zip does not contain a logs/ directory, please attach the log file manually:

  • macOS / Linux: ~/.clacky/logger/clacky-YYYY-MM-DD.log
  • Windows: C:\Users\<your-username>\.clacky\logger\clacky-YYYY-MM-DD.log

There's one log file per day, and we keep at most 7 days. The file from the day the bug happened is the one we need.

What to Include in Your Bug Report

The zip alone isn't enough. Please also tell us:

  1. OpenClacky version — clacky --version in a terminal, or check the "About" page in the Web UI.
  2. Operating system — e.g. macOS 14.5 / Ubuntu 22.04 / Windows 11.
  3. Reproduction steps — what you did → what you expected → what actually happened.
  4. Approximate time — when the bug occurred (minute precision is fine), so we can locate the right window in the log.
  5. Screenshot or screen recording (optional, but very helpful).

Privacy Notes

session.json and the log files may contain:

  • Every prompt and file content you fed to the AI
  • Tool inputs and outputs (file snippets read, command output, etc.)
  • The model base URL and model name you configured
  • Local file paths surfaced in error stack traces

They will not contain:

  • Your API key (redacted in both session and logs)
  • System passwords / SSH private keys (we never read these)

If your conversation involved sensitive content, before sending the zip you can:

  1. Unzip it and open session.json and logs/*.log in a text editor;
  2. Replace any sensitive snippets with [REDACTED], then re-zip and send.

Where to Send the Report

Send the zip (or copied log content) + the info above to any of:

  • GitHub Issues: openclacky/openclacky (preferred — easier to track)
  • Enterprise customers: your dedicated support channel

Don't paste the zip's raw contents into a public issue body — use GitHub's file-attachment feature so search engines won't index sensitive bits.