clawpilot-doctor

name	clawpilot-doctor
description	Use when the user wants to diagnose or repair ClawPilot host issues for OpenClaw, Hermes, or cc-connect Coding Agent hosts, including status checks, logs, restart, update, and self-repair. Focus on the concrete blocking issue and the next corrective action.

ClawPilot Doctor

Use this skill for ClawPilot host troubleshooting across supported runtimes:

• openclaw
• hermes
• ccconnect

When To Use

Use this skill when the user asks to:

• Check ClawPilot or Gateway status
• Read logs
• Restart the Gateway
• Update OpenClaw
• Run repair or diagnostics
• Diagnose Hermes API or cc-connect bridge readiness

Do not use this skill to generate a pairing code or send files back to PocketClaw.

Preferred Actions

Use the smallest action that answers the question or fixes the issue:

• clawpilot status
• clawpilot restart
• Host commands already exposed through the current OpenClaw or relay setup
• Confirmed repair commands such as OpenClaw self-repair paths

When the host has multiple runtimes, evaluate them separately:

• OpenClaw
  • relay
  • local gateway
• Hermes
  • relay
  • Hermes API
  • Hermes Agent Bridge Python/runtime
• ccconnect
  • relay
  • cc-connect Management API
  • cc-connect Bridge WebSocket

For Hermes-specific failures, prefer checking:

curl http://127.0.0.1:8642/health

and the current ~/.hermes/.env values for:

• API_SERVER_ENABLED
• API_SERVER_KEY

If Hermes API is healthy but sending a message fails with Hermes agent Python not found or Hermes Agent Bridge unavailable, treat it as a Hermes runtime/config problem, not a PocketClaw connection problem. Check:

which hermes
node -e 'try { console.log(JSON.parse(require("fs").readFileSync(process.env.HOME + "/.clawai/runtimes/hermes.json", "utf8")).hermesAgentPythonPath || "") } catch {}'
ls -l "$(dirname "$(which hermes)")/python"
ls -l "$HOME/.local/hermes-agent/.venv/bin/python"
ls -l "$HOME/.local/hermes-agent/venv/bin/python"
ls -l "$HOME/.hermes/hermes-agent/.venv/bin/python"
ls -l "$HOME/.hermes/hermes-agent/venv/bin/python"

Also inspect the active Hermes config ($HERMES_HOME/config.yaml, the active profile config, or ~/.hermes/config.yaml) for any configured agent/python/runtime path. Validate the chosen Python with:

test -x /path/to/python
/path/to/python -c 'import hermes_cli, hermes_state, run_agent, yaml'

Repair based on the concrete failure:

• Wrong configured path: fix the Hermes config or active profile config.
• Existing but non-executable Python: chmod +x /path/to/python.
• Missing venv/runtime or failed imports: reinstall or repair the Hermes agent runtime.
• Stale hermes on PATH: fix PATH so which hermes points to the current Hermes install.

After repair, restart ClawPilot and verify clawpilot status shows both Hermes API and Hermes Agent Bridge healthy before testing a chat message.

For ccconnect-specific failures, prefer checking:

command -v cc-connect
cc-connect --help
cc-connect daemon status
clawpilot status

Then inspect both the cc-connect app config and the current ClawPilot runtime config:

• ~/.cc-connect/config.toml
  • configured [[projects]]
  • [projects.agent] type and work_dir
  • [projects.agent.options] work_dir exists and is writable
  • work_dir is not /
  • [management] enabled/port/token
  • [bridge] enabled/port/token
• ~/.clawai/runtimes/ccconnect.json
• management API URL/token
• bridge URL/token
• selected coding agent command availability, such as claude, codex, or gemini

If cc-connect is missing, install it before retrying pairing:

npm install -g cc-connect@latest

If cc-connect is installed but not configured for PocketClaw pairing, prepare the ClawPilot config and daemon before pairing:

clawpilot prepare-ccconnect
cc-connect daemon install --config ~/.cc-connect/config.toml
cc-connect daemon restart

For PocketClaw ccconnect pairing, treat the cc-connect daemon as the stable runtime path. clawpilot prepare-ccconnect creates a PocketClaw placeholder channel; do not replace it with a dummy platform or ask the user to choose Feishu, Telegram, Discord, WeCom, or Weixin. Do not recommend cc-connect &, shell background jobs, or terminal(background=true) as a stable fix. ClawPilot must not start cc-connect itself.

After installing/upgrading cc-connect or changing ~/.cc-connect/config.toml, clear the old service and reinstall it with the explicit config path:

cc-connect daemon stop || true
cc-connect daemon uninstall || true
cc-connect daemon install --config ~/.cc-connect/config.toml
cc-connect daemon restart
cc-connect daemon status

If the daemon fails, inspect logs before guessing:

cc-connect daemon logs -f

If the Bridge is expected on the default port, verify it is listening:

lsof -i :9810

Output Rules

• Report what you checked.
• Report what failed or passed.
• If blocked, give the next command to run.
• Keep the result concrete and operational, not theoretical.

Do Not

• Do not jump into pairing unless the user explicitly wants pairing.
• Do not modify unrelated config when a status or log check is enough.
• Do not claim a repair is complete without verifying the result.