---
name: Clash Doctor
slug: clash-doctor
category: Automation
description: Clash Doctor inspects Clash Verge and mihomo, manages profiles and routing, and diagnoses connectivity issues. Use it for proxy failures, AI tool routing, local hub alignment, TUN bypasses, or when a sync did not apply.
github: "https://github.com/majiayu000/spellbook/tree/main/skills/clash-doctor"
language: Python
stars: 265
forks: 26
install: "npx degit https://github.com/majiayu000/spellbook/tree/main/skills/clash-doctor ~/.claude/skills/clash-doctor"
installs_to: ~/.claude/skills/clash-doctor
source_path: skills/clash-doctor/SKILL.md
collection_size: 25
category_size: 1648
collection_url: "https://dirskills.com/collections/majiayu000/spellbook"
added: 2026-09-02T05:19:37.826Z
last_synced: 2026-09-02T05:19:37.826Z
canonical_url: "https://dirskills.com/skills/clash-doctor"
---

# Clash Doctor

Clash Doctor inspects Clash Verge and mihomo, manages profiles and routing, and diagnoses connectivity issues. Use it for proxy failures, AI tool routing, local hub alignment, TUN bypasses, or when a sync did not apply.

**Install:**

```bash
npx degit https://github.com/majiayu000/spellbook/tree/main/skills/clash-doctor ~/.claude/skills/clash-doctor
```

## README

# Clash Verge Diagnostics

Inspect Clash Verge or mihomo, manage profile-specific routing, and diagnose connectivity.

## Routing

- Confirm the target profile, constraints, requested access path, and done-when signal.
- Load `references/full-guide.md` for commands, templates, and diagnosis matrices.
- Load `references/local-hub.md` before `hub`, `align`, `roles`, `clone`, `setup-ai`, or `switch`, and whenever the user says a previous sync did not apply.
- Keep the change limited to the requested target.

## Safety

- Diagnose and align are read-only. Writes require a shown summary and explicit confirmation.
- Edit enhancement overlays or the confirmed local-hub YAML. Do not edit raw subscription dumps.
- `tun.route-exclude-address` is union-only. `DIRECT` is not a TUN bypass.
- Never invent or print node IPs, credentials, subscription UIDs, or machine hostnames.
- After an overlay or hub-YAML write, quit and reopen Clash Verge. `PUT /configs` does not re-merge overlays.

## Modes

| Argument | Mode |
|---|---|
| empty or a hostname | diagnose |
| `profiles` / `list` / `ls` | list local and remote profiles |
| `status` | live kernel, TUN, and selected nodes |
| `hub` / `roles` | local-hub topology |
| `align` / `sync-check` | read-only multi-machine comparison |
| `switch-check` / `health` | pre-switch health |
| `clone` / `setup-ai` / `switch` | confirmed profile writes |
| `rustdesk` / `bypass` | TUN exclusion for a relay IP |

Resolve the named target before `setup-ai`. Apply airport-style enhancement overlays only when that target is `type: remote`; edit the named hub YAML when it is `type: local`.

## Verify

- Parse the target YAML after every write.
- Query mihomo by trying both Unix sockets and then the configured HTTP controller; fall back on request failure, not socket existence alone.
- For routes, `chains[-1]` is the matched group and `chains[0]` is the dialed node.
- Report files changed, commands run, evidence, and remaining risk.

## References

- `references/full-guide.md` — commands, templates, and diagnosis matrix
- `references/local-hub.md` — hub ownership, node roles, alignment, and landmines