DUNHKpcc/Claude-Guardian

Claude Guardian is an all-in-one Claude account safety and risk prevention skill.Claude防封实战 It intelligently assesses your device, account history, network environment, and payment options, then provides personalized guidance for local, VPS, or virtual machine setups.

What is Claude-Guardian?

Claude-Guardian is a "Skill" — a packaged set of instructions, reference materials, and scripts — that you give to an AI coding agent (specifically one that supports the "Skills" feature, like Codex). Its job is to guide you, step by step, through setting up a safe and stable environment for using Claude (the AI assistant).

Think of it as a checklist-and-coach package: the agent reads your situation, asks you questions, and then walks you through things like choosing where to run Claude, setting up a fixed network exit IP, configuring firewalls, and managing your account safely.

What does it actually do?

The README lists these main capabilities:

Area	What it helps with
Route selection	Choose between running Claude on your own computer (local), in a virtual machine (VM), or on a remote server (VPS). It explains the trade-offs of each.
Fixed exit IP	Explains three ways to get a stable network identity: commercial proxy services ("airport" services), self-hosted proxies, and shared residential bandwidth. Includes 17 VPS recommendation reports.
Account registration	Recommends a beginner-friendly combo (Apple in-app purchase + Gmail/Outlook + VPS IP + VM or local + Pro plan), plus guidance on email providers, upgrade timing (Free → Pro → Max), and mobile anti-ban checklists.
Payment	Suggests payment methods based on your region/device/budget, but you always complete the payment yourself.
VM setup	Guest OS choices (Omarchy, macOS), LAN network card setup, build order, and a "fail-closed" firewall script (blocks traffic by default unless explicitly allowed).
VPS setup	Using a VPS as a development machine: Ubuntu 24.04, remote desktop (Xvfb + noVNC), VS Code Remote-SSH, tmux, inbound firewall scripts.
Local setup	Configuring Clash Verge / FlClash with TUN mode and DNS, Windows Firewall, Mac's LuLu firewall — with prompt-based guidance.
Whole-machine unified exit	Ensures your entire machine only uses IPv4 (not IPv6), with strict routing, DNS settings, leak detection, and a verification script that judges whether the setup is "established / violated / incomplete" based on observed evidence.
Line optimization	Diagnoses and optimizes your network path: SSH dynamic forwarding, Realm relay, BBR congestion control — each change is recorded and can be rolled back.
Error handling	Guides you through common Claude errors (403, 429, 529), billing conflicts, and suspected credential leaks — pause, gather evidence, then act.
Cleanup planning	Plans how to remove leftover Claude data from old devices (Mac, Windows, Linux), and how to clean proxy/VPN logs and terminal history after a ban. Never permanently deletes — always reversible with your confirmation.
Source links	Every answer includes links to the source material. Can also be used as a search tool for forum posts about VPS, residential bandwidth, network lines, and ban experiences.

Key principles (the "bottom lines")

The README is explicit about boundaries:

Money and accounts are yours: You do all payments, registrations, logins, KYC, and OAuth yourself.
No credentials requested: The tool never asks for your IP, subscription links, passwords, UUIDs, or full configs.
No touching Claude during preparation: It won't launch the client, log in, or access Claude's services during setup.
Adapts to your environment: The author tested on their own Mac, Windows, VM, and VPS. Your system may differ, so the agent verifies and adjusts — and rolls back if something breaks.
No guarantee against bans: Prices and access rules change fast; check official pages before buying.

How it works

You describe your needs and environment.
The agent (using the Skill) understands, judges, and explains.
It uses an interview state machine — hundreds of questions scheduled by conditions. It only asks route-specific questions after you've chosen a route, and it records your authorizations.
It pulls from a reference library (sections S01–S08, R01, R02) and runs scripts — either you run them yourself, or the agent runs them with your approval.
Verification and rollback happen after any change.

Three-tier authorization (you don't need to be present for every step)

Changes are classified by risk level:

Tier	What you do	What's included
🟢 A — Do within scope	Confirm the scope once after choosing a route	Read-only diagnostics, research, proposals, dry runs
🟡 B — Approve a plan once	Approve a single plan; agent executes continuously, auto-rolls-back on failure	Installing clients, adding allow rules, port forwarding, temporary BBR, installing TUN
🔴 C — Must confirm each time	Agent pauses and waits for your explicit reply	Switching default outbound to block, enabling firewalls, changing SSH, persistent kernel changes, cleaning data, anything involving accounts/money/credentials/org devices, or touching Claude itself

Your approvals are recorded in the interview state. If you switch routes, you need to re-confirm.

Installation

Copy the skills/claude-guardian folder from the repo into your Codex Skill directory (e.g., ~/.codex/skills/ on macOS/Linux, %USERPROFILE%\.codex\skills on Windows).
Requires a Codex version that supports Skills, and Python 3.10+ for scripts.
The install script stops if a target already exists (to avoid overwriting custom content).
You can read the Skill and reference docs without running any scripts.

Then start a conversation in Codex like:

$claude-guardian
I'm preparing to subscribe to Claude for the first time, using a Mac. Help me compare local vs. VM first, then decide how to check.

Three routes (parallel choices, not a progression)

Route	Best for	Key tools
Local	Using Claude directly on your own Mac/Windows (default recommendation)	Clash Verge, FlClash, LuLu, Windows Firewall
VM	Building an isolated work environment in a virtual machine	Omarchy (or macOS on Mac hosts), FlClash TUN, nftables
VPS	Using a remote server as your dev machine (Claude Code runs on the VPS)	Ubuntu 24.04, Xvfb + noVNC, VS Code Remote-SSH, tmux

Note: Using a VPS as a network exit is not the same as choosing the VPS route.

Included scripts (developer section)

The repo ships several command-line tools (all in skills/claude-guardian/scripts/):

interview_cli.py — full interview flow with resume support
guardian.py — simplified interview + system/proxy checks
network_check.py — network diagnostics (routing, IPv4/IPv6, DNS leaks, UDP, failure drills)
egress_verifier.py — judges whether the machine is truly IPv4-only
status_dashboard.py — generates an offline HTML report dashboard
inventory_cli.py — capability queries and config audits
agent_remediation.py — picks remediation actions from reports
repair_cli.py / recovery_cli.py — precise file repair with receipts and rollback
cleanup_cli.py / native_cleanup_mac.py — Claude data cleanup (macOS has a built-in host)
serve_webrtc.py — serves a local WebRTC test page

Output files never overwrite existing files — they always write new ones.

Documentation & community

Wiki: user-facing tutorials (auto-generated from the repo)
Reference docs: organized by topic (routes, accounts, payments, mobile, egress IPs, firewalls, VM/VPS guides, line optimization, incidents, source library)
Community: Telegram channel and QQ for sharing experiences; GitHub Issues for bug reports and suggestions
License: GPL-3.0-only
Testing: unit tests, compile checks, and CI on Linux/macOS/Windows; the author verified everything on real hardware (Mac, Windows, VM, VPS)

In one sentence

Claude-Guardian is a guided, safety-conscious setup assistant that helps you prepare a stable, secure environment for using Claude — without ever touching your money, credentials, or Claude itself without your explicit approval.