EN Usage Guide

中文 | English

Usage Guide

This is the complete usage overview of FlowWeaver. Follow the first four sections in order to get up and running.

1. Install and First Run

1. Download the stable build for your platform from Releases (both GUI and CLI are provided, 12 build targets total; per-platform notes in Platform_EN.md).
2. GUI: run FlowWeaver.exe. CLI: run flowweaver to open the TUI panel.
3. Run as administrator is recommended: system proxy writes and TUN mode require elevation; autostart (via Task Scheduler) also requires it, and once configured it launches at logon without a UAC prompt.

2. Import a Clash Subscription

The primary workflow of FlowWeaver is importing an airport Clash subscription:

• GUI: open the Subscription page and paste your subscription link. Once activated, its nodes, proxy groups and routing rules load automatically, and the built-in rules are hidden.
• CLI:

flowweaver sub add https://example.com/subscribe MyProvider  # import (name inferred from the URL if omitted)
flowweaver sub use MyProvider                                # activate and load its rules
flowweaver sub update                                        # update the current subscription

Without a subscription, FlowWeaver also works as a rule-based proxy (built-in rules provide no node selection).

3. Pick a Node

• GUI: the Proxies page offers a Clash Verge-style node list; switch nodes per proxy group.
• CLI:

flowweaver sub nodes                   # list proxy groups and nodes
flowweaver sub current                 # show the active subscription and selected nodes
flowweaver sub select Proxy "HK-01"    # select a node for a group
flowweaver sub test                    # test every node's connectivity

Supported protocols: ss (AEAD-2022), vmess, vless (TCP / WebSocket), trojan, tuic, hysteria2, wireguard, socks5, http. Every protocol except http supports UDP forwarding (including QUIC / HTTP3). WireGuard tunnels run on a userspace IP stack — no kernel NIC is created and the system routing table is untouched.

4. Start the Proxy and Choose a Traffic Capture Method

Once started, FlowWeaver serves HTTP and SOCKS5 on the same mixed port (configurable in Settings):

Method	Description
System proxy	Writes the system proxy setting; browsers follow immediately
TUN virtual NIC	Transparently captures all traffic with auto-routing and DNS hijacking; TUN UDP traffic is also forwarded through the currently selected subscription node

5. Proxy Modes

Each site group can use one of the following modes (usable with built-in rules when no subscription is active). Full details in Core Proxy Modes:

Mode	One-liner
Transparent	Only fixes DNS / target IP — for plain DNS pollution
MITM	Terminates TLS locally, re-handshakes with custom SNI / ECH (root certificate required)
QUIC	Re-emits outbound as HTTP/3 direct replay
TLS-RF	TLS handshake fragmentation with precise cut points and timing perturbation
Migration	Session migration (migration status|on|off|server|test)
Direct	Direct connection

6. Certificate (required for MITM / QUIC)

• GUI: Settings → Certificate Management → Reinstall Certificate — see Certificate Installation.
• CLI: flowweaver ca install (admin / root required).

7. Advanced Features

• Smart routing: GFWList-based automatic identification of blocked domains — see Auto Routing; rule optimization ideas in the Custom Rules Guide.
• Encrypted DNS (DoH): anti-pollution resolver with multi-node failover (dns list|test).
• ECH injection: automatically fetches and injects ECH Config (ech fetch <domain>).
• Cloudflare IP pool: auto speed-test, health checks and refresh (cf status|refresh|health).
• NAT64: IPv6 egress when IPs are restricted (nat64 list|test).
• Evolution mode: automatically tests rule combinations to find the optimal access method (evolution start).

8. Autostart

• GUI: enable in Settings. Uses the Windows Task Scheduler; starts at logon without a UAC prompt.
• CLI: flowweaver autostart on --with-proxy (separate entry, does not affect the desktop app).

9. Command Line (CLI)

Run flowweaver with no arguments to open the TUI; single commands like flowweaver status, flowweaver tun on work directly. See the full catalog (including the subscription group) in the CLI Reference. For a quick end-to-end check run flowweaver selfcheck.