reference / troubleshooting

Find what failed, check it, fix it.

Each table goes from what you see to one check and one fix. Work from the machine outward: the daemon, the console, the Session list, the browser, then Cloud.

Checked against the product on 6 October 2026

Latest release: Clawdline v2.9.0 · platform support

clawdline doctor                                                 # version, port, state directory
curl -s http://127.0.0.1:7727/v1/health                          # "ok":true,"served_by":"clawdline-go"
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:7727/   # 200 means the console is served

The daemon and the console

You see	Check	Fix
The daemon exits with status 3	`logs/daemon.log` names the process on the port.	Stop it, or start with another `CLAWDLINE_NEXT_PORT`.
`the daemon did not answer`	Is `serve` running, on the same port as the command?	Start it, or give both the same `CLAWDLINE_NEXT_PORT` and `CLAWDLINE_NEXT_DIR`.
`501 no_web_root` on `/`	The log says `console: NONE`.	Restart with `CLAWDLINE_NEXT_WEB="$PWD/web/console/dist"`.
`500 no_document` on `/`	The log says `console: BROKEN`.	Rebuild: `(cd web && npm install && npm run build)`.
`501 not_implemented` on a `/v1/` route	The body names the route.	Nothing; this daemon does not serve that route yet.

An AI agent in a sandbox may not reach 127.0.0.1 while the daemon is fine. Repeat the health check from a normal terminal before you conclude it is down.

Sessions and sending

You see	Check	Fix
A Session is missing	In its terminal, `echo "$TMUX"` prints something; `tmux -V` works for the user running the daemon.	Run the assistant inside tmux, or in iTerm2 on a Mac (Terminals).
The list is empty on Windows	—	Windows cannot list Sessions (Platforms).
A state reads 狀態未知	Open the Session's live screen.	Nothing; the state returns when Clawdline can read it again.
The browser shows a pairing page	It has no device.	Run `clawdline open` on the machine.
Typing is refused	The device is read-only, or this machine has not allowed Cloud operation.	For Cloud, use this machine's Settings → Remote to allow operation. For local access, run `clawdline open` again (Read and send).
Claude's `5h`/`7d` show as unknown	Does `~/.claude/statusline-cache/rate-limits.json` exist?	Configure a Claude Code status line that writes it (Usage).

The Cloud line

clawdline cloud preflight   # each setting marked ok, warn, or block, with the next step
clawdline cloud status      # the switch, the account, and this machine

You see	Check	Fix
The line stays down	Settings → Remote names the connection error; the CLI also prints `clawdline cloud status`.	Follow the stated reason. The Settings controls need no manual restart; restart a manually running `serve` after a CLI switch.
`not_signed_in` or `device_not_approved`	Settings → Remote shows account sign-in separately from the line.	Sign in and approve the machine there; the CLI equivalent is `clawdline cloud login`.
`entitlement`	The plan's machine or device limit is reached.	Free a slot, or change plan on the 方案 (Plan) page.
`version_mismatch`	See Updates.	Update this machine.
`machine_offline` on a command	Is the machine on, and does `status` show `enabled true`?	Retry once it is online. The command was not queued.

Updates

The daemon compares its build with the latest one at app.clawdline.com, at start and every 30 minutes. An older machine can show 讀取失敗 (Failed to load) beside newer console features.

clawdline update            # running and latest build, and the state
clawdline update --apply    # Linux source checkout only

Exit status: 0 current or ahead, 10 behind or different, 3 unknown.
When the machine is behind, 設定 (Settings) shows one line naming both builds and clawdline update --apply.
--apply on a Linux source checkout builds and deploys the latest build, and rolls back if it fails. On macOS it changes nothing: it prints the commands to run.
To turn the check off, set CLAWDLINE_NEXT_UPDATE_CHECK=off.

File a bug

Open an issue at github.com/sainteye/clawdline/issues with the clawdline doctor output, your operating system and assistant version, the time of the action, the matching logs/daemon.log lines with paths and tokens removed, and the shortest steps that reproduce it.