When a macOS VPN misbehaves, the route is rarely the cause. Usually the installer was never allowed, the network extension never got permission, or the imported subscription never triggered an update. This guide follows the real order of operations — install, allow, authorize, import, verify — and spells out what you should see at each step, plus where to look first when you don't.
Nothing here requires changing low-level system settings or turning off any protection. Any tutorial that asks you to disable system protections before connecting can be skipped.
Line up three things before you install
Getting these three ready before you start saves half the back-and-forth later.
An admin account. Installing the client and approving the network extension both need administrator rights. On a standard account the Allow button simply never appears — not because the client is broken, but because the system doesn't send the prompt to that account. Confirm the current account is an admin before you begin.
The subscription link. Sign in to the user panel and copy the subscription link from the downloads and subscription section. The link carries a token and works like account credentials — don't post it in group chats or leave it in screenshots.
Your use case. Decide up front whether this Mac routes everything through the proxy or splits traffic by rule. You can change the mode later, but picking wrong at the start makes you misread the result as a route problem during verification.
- ✅ The current account is an administrator and can open Privacy & Security in System Settings
- ✅ The subscription link is copied locally, not relayed through a chat app
- ✅ Two test sites ready — one in mainland China, one international — to check split routing
- ❌ Installing straight onto a Mac managed by a corporate configuration profile — the network extension may be blocked by policy
- ❌ Taking an installer from a cloud drive or forum — an unknown source means you can't verify the signature
Allowing the installer: three blocks and what to do about each
The download is usually a dmg. Open it and drag the app into the Applications folder — don't double-click it inside the Downloads folder. The quarantine attribute travels with the file; leaving it in Downloads makes it easy for cleanup tools to delete and more likely to break on later updates.
The first launch will most likely be stopped by the system with a message that it can't be opened because Apple cannot check it for malicious software. The installer isn't broken — that's the source check. Open System Settings → Privacy & Security, find the blocked entry near the bottom of the page, click Open Anyway, then launch it once more from Finder and the dialog will come back with a confirm button.
The second message says the app is damaged and should be moved to the Trash. Most of the time the download was incomplete, or a download manager rewrote the file attributes. Just download it again. The terminal "fix" commands floating around the web switch off quarantine checks globally — not recommended on a machine you rely on, since they silence the message rather than solve the problem.
The third case: no entry appears in Privacy & Security at all. That means the app never ran, so the system never got to the check. Work through it in order — was it really dragged into Applications, did the dmg mount completely, did security software block it first?
To tell whether an installer is intact, the signature is more reliable than the file size. Right-click the app and choose Get Info, or run codesign -dv in Terminal to inspect the signature. If the signature is missing or doesn't match the official one, don't install it.
Approving the network extension: two switches
Most VPN clients on macOS run as a system network extension rather than a plain app. That means the first connection adds two confirmations, and both appear only at specific moments — miss them and you have to fix it by hand.
First: the add-VPN-configuration prompt
The first time you hit Connect, macOS asks whether the client may add a VPN configuration, and wants your password or Touch ID. If you cancel here, the client UI usually still responds to clicks, but the status sits on Connecting forever and never recovers on its own.
Second: the network extension switch
Open System Settings → General → Login Items & Extensions → Network Extensions and make sure the client's entry is on. The exact location shifts between major versions and it can also show up under Privacy & Security. Turn this off and the connection drops instantly, with no reason given.
When permission isn't granted properly, three symptoms are typical: the menu bar icon changes colour but stays on Connecting; it connects for a few seconds, drops, and returns to disconnected; or a grey VPN configuration with a warning badge appears under System Settings → Network.
The fix order is fixed: quit the client → delete the leftover VPN configuration in System Settings → Network → reopen the client → go through the allow flow again. Clicking Connect repeatedly won't make the system re-issue the prompt; it just piles up more leftover configurations.
Don't "solve" connection problems by disabling System Integrity Protection or turning the firewall off wholesale. Once those are off the problem is only hidden, later diagnosis gets several times harder, and the impact isn't limited to one client.
Importing a subscription: link, QR code, or manual parameters
A freshly installed client is empty — nodes come from the subscription link. Pick one of the three methods to suit the situation; don't mix them.
Option one: paste the subscription link
In the client's subscription or profile section, choose import from link, paste, and confirm. A successful import pulls the node list immediately, and the list should show entries grouped by region. If the list is empty, first check whether a chat app truncated the link — a few missing characters from copying is the most common cause.
Option two: QR code
A QR code is just the same link in graphic form, handy for scanning straight from the panel. On a Mac, scanning with a phone and pasting back on the computer adds a step; pasting the link into the client is faster and less error-prone.
Option three: add a single node manually
Use this only when you have single-node parameters. The fields differ by protocol: Shadowsocks needs a password and a cipher; VMess needs a UUID, plus alterId on older versions; VLESS needs a UUID and an optional flow; Trojan needs only a password; Hysteria2 and TUIC are QUIC-based and need authentication details plus congestion-control parameters. One wrong character and it won't connect — hand-copying parameters is the most error-prone step in the whole process.
The subscription link contains a token, so anyone who has it can spend your traffic allowance. If you suspect a leak, reset the subscription URL in the user panel and import again in the client. The old link stops working immediately, including the copy in use on your other devices.
Update manually once after importing
The client doesn't notice when nodes change on the backend. Click update subscription once in the client and confirm the node count and regions have changed. Most clients support scheduled updates at an interval you set, but after switching machines or resetting, do that one update by hand.
The signs of a successful import are specific: the node list appears grouped by region, entries can be selected, and the status bar shows the selected node's name. If any of the three is missing, suspect an incomplete subscription before you suspect the route.
Checking connectivity: four confirmations
Connected doesn't mean working. The four steps below pin the problem to a specific layer instead of blaming "a bad route" in general.
- Check the exit region. Once connected, open this site's "My IP" page and see whether the country and region it detects match the node you picked. If they don't, your traffic isn't going through the proxy at all — go back to the client's system proxy or TUN switch.
- See which side resolves DNS. If lookups are still handled by the local ISP, international sites can resolve to a nearby but wrong address, which shows up as inconsistent speed and images that load halfway. Split-tunnel rules should hand DNS queries to the proxy side as well.
- Verify the split rules. Open one site in mainland China and one international site, and confirm the first goes direct while the second goes through the proxy. A common mistake is routing an entire top-level domain direct, which sends every target under it around the proxy.
- Check IPv6. When the local network hands out both IPv4 and IPv6 and the client only captures IPv4, some sites leave over IPv6 directly — pages open but video stalls. Either disable IPv6 in the client or make the rules treat both protocols the same way.
Verification comes down to two things: is the exit region right, and has DNS fallen back to the local resolver. When both are fine, then question route quality — doing it in the reverse order just wastes node switches.
Symptom lookup: where to check first when it won't connect
The table below works backwards from symptom to cause, ordered from most to least common. Run down it row by row and you can usually skip the wasted attempts.
| Symptom | Common cause | What to do, in order |
|---|---|---|
| Client says connected, but the browser won't load pages | System proxy was never set, or a rule sends the target direct | Check the client's system proxy and TUN switches first, then which rule matched |
| Disconnects by itself a few seconds after connecting | Network extension permission was never completed, or a management policy blocked it | Quit the client, delete the leftover configuration, authorize again |
| Only a few sites fail, everything else is fine | A split rule is wrong, or the site itself is region-locked | Retest with another node in the same region, then go back to the rules |
| The page reports a certificate error | The client's decryption feature isn't trusted by the system, or the system clock is far off | Sync the clock first; turn the feature off if you don't need it |
| The node list is empty after updating the subscription | The link was truncated, or the token was reset in the panel | Copy the link again from the panel and import it once more |
| Upload and download are both slow, and switching nodes doesn't help | Local network congestion, or the route type doesn't suit this time of day | Try a different route type (dedicated / relay) against the same target |
System upgrades and uninstalling
After a major macOS upgrade, the network extension's authorization may be reset. If the first connection after upgrading sits on Connecting, just re-check the extension switch in System Settings — no need to reinstall the client or re-import the subscription.
Uninstalling takes the full sequence: quit the client → delete the matching VPN configuration in System Settings → Network → remove the extension under Login Items & Extensions → finally delete the app. Drag the app to the Trash alone and the leftover configuration stays in the network list, where it can collide with the next client you install and knock out the new configuration.
A new machine doesn't mean buying again: import the same subscription link on the new Mac — the account has no device limit. Clean the old machine out with the steps above so two configurations don't fight over the system proxy and make both look flaky.
Fix the order
The sequence is fixed: install → allow → authorize → import → verify. When you get stuck, walk back through it in that order — permissions first, then rules, and only then the route. The vast majority of "won't connect" cases on macOS stop at the first two steps, and those are exactly the steps that give no clear error.
Permission issues account for most macOS cases, and they all look like "the network is down". Get the installer allowed and the network extension authorized first — only then do subscriptions and split rules mean anything.