Troubleshooting a failed connection

Match your symptom to one of these four first — the cause is different for each.

Stuck on “Connecting to Agent…”

The Agent process has died. The most common cause is running it in a terminal window that then got closed, killing the process with it.

Install it as a system service so it stays running in the background.

Shows “offline” but the Agent is still running

The connection never formed. Check the Agent’s logs first for a platform-not-supported error — on some platforms, missing components let pairing succeed while the connection itself never comes up.

Running the Agent on Linux, macOS, or in a container is currently the more stable option.

Connection drops on and off mid-conversation

Update both the client and the plugin to the latest version and see if it persists. Also check whether the machine goes to sleep — once it does, the Agent process stops with it, the connection drops, and ClawChat has no way to wake it remotely.

If you need the Agent to stay online continuously, running it somewhere that never sleeps — a server, an always-on machine, or a container — is the most reliable fix.

Registered, but it never comes online

Usually a pairing-code issue. Codes are single-use and expire — don’t retry the same one. Generate a new code, activate again, then restart the Agent.

If it activates but you never get a greeting message, the restart step is almost always the reason.

Plugin installation fails

ClawChat’s own services are directly reachable from mainland China without anything special. Install failures usually happen on the code-hosting side, which is where the installer fetches files from by default.

You can usually work around this with the “install directly via the host” option — repeatedly forcing a reinstall just retries the same failing path.

If a clawchat-related command isn’t found, it’s rarely a typo — it usually means the plugin never finished installing.