First move in almost every case:
npx -y @dataworkers/dw-claw@latest doctor
The doctor checks Node version, client registration, and connector configuration, and names
what’s wrong.
| Symptom | Likely cause | Fix |
|---|
npx fails or hangs | Node < 20, or a corporate npm proxy | node --version; if proxied (Artifactory/Nexus), mirror the public packages or ask your named engineer for the proxy setup |
401 / E404 installing a private package | Customer npm token missing or expired | Re-run npm config set //registry.npmjs.org/:_authToken=<token>; tokens expire with your term — ask for a fresh one |
| MCP server not listed in the client | Registration step skipped or client not restarted | Re-run the add/config step for your client, restart it |
| Tools listed but every call times out | The server process can’t start in your environment | Run the doctor; check for MDM or sandbox restrictions on spawning npx |
| Symptom | Likely cause | Fix |
|---|
| Everything answers with sample data | 🟡 Evaluation state — no verified connection | Set the system’s env vars (connector pages) in the shell your client launches from, restart, then verify |
| Env vars set, still sample data | Vars not visible to the MCP process | Set them where the client is launched (shell profile, not just one terminal); restart the client |
| Verification fails: authentication | Wrong credential, or expired | Re-check the value; try the same credential with the system’s own CLI |
| Verification fails: permission | Grant narrower than the minimum | Add the missing grant; re-run the test |
| Verification fails: network | Private endpoint, VPN, IP allowlist | Confirm the machine running agents can reach the system at all (curl its endpoint); allowlist it |
| A system flipped 🟢 → 🔴 | Token expiry, tightened permissions, or network change | The 🔴 message names the failing check; fix and re-verify — this is the model working, not a bug |
| Symptom | Likely cause | Fix |
|---|
| Console opens, no tools | Local brain didn’t start | Restart npx @dataworkersproj/agent-console@latest serve --local-ui; Node 20+ |
| Connector card added but grey | Test connection not run yet — by design | Press Test connection |
| Your system has no console card | Console list is a subset today | Connect via env vars in the terminal path |
- File a bug — include OS, Node version, client (harness), the exact
error, and whether npm is proxied. AI agents can file on your behalf.
- Scale/Enterprise: your named engineer / support channel, with the same details.
- Open source: GitHub issues on the repo.