TOPIC / RESOURCE

OpenClaw troubleshooting: triage before you fix

Triage installation, model, channel, auth, and Docker issues systematically. Start with doctor, repair, and gateway restart before guessing at root causes.

Best for

安装好了但不能用，或者不确定坏在哪一层
想先把问题缩成安装、模型、渠道、认证或 Docker
希望先用 doctor 和最小动作收敛，而不是直接重装

Before reinstalling, narrow the layer

The first useful action is not a reinstall. Determine whether the problem is in installation, model, channel, auth, doctor, or Docker.

Minimal diagnostic commands

Memorize these first:

openclaw doctor
openclaw doctor --repair
openclaw gateway restart
openclaw logs --follow

Basic checks:

node -v
npm -v
python3 -m json.tool openclaw.json

Common issues

Issue	Symptoms	First action
Install failure	Dependencies fail, version mismatch	Check system requirements and Node
Port conflict	Service won't start, "port in use"	`lsof -i :8080` — kill or change port
Version mismatch	Old commands fail, config differs	Check current version and docs
Env vars	Model key set but missing	`echo $ANTHROPIC_API_KEY` — fix if empty
Model issues	Chat works, real tasks fail	"No model" vs "visible but unusable"?
Channel not triggering	Bot visible, no/inconsistent reply	Minimal message loop only
Auth problems	Entry unstable, unauthorized access	Check gateway auth before model
Docker issues	Paths, env, permissions mixed	Confirm container paths match
Host from Docker	`localhost` fails	Use `host.docker.internal`
File rules	AGENTS.md/SOUL.md ignored	Check case, location, restart reload