Home/stef-openclaw-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand nordvpn client setup and troubleshooting

Browse Source
This commit is contained in:
Stefano Fiorini
2026-03-12 02:45:21 -05:00
parent 7d8eb89911
commit e6dccb5656
3 changed files with 476 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
skills/nordvpn-client/SKILL.md
View File

@@ -7,14 +7,14 @@ description: Use when managing NordVPN on macOS or Linux, including install/boot
Cross-platform NordVPN lifecycle management for macOS and Linux hosts.
## What This Skill Is For
## Use This Skill For
- Probing whether NordVPN is already installed or automation-ready
- Bootstrapping the required NordVPN backend if it is missing
- Logging in through the Linux CLI or validating a NordVPN token for the macOS WireGuard backend
- Connecting to a country or city before a follow-up action such as `web-automation`
- Disconnecting and checking VPN status
- Verifying public IP and geolocation after connect
- probing whether NordVPN automation is ready
- bootstrapping missing backend dependencies
- validating auth
- connecting to a country or city
- verifying the public exit location
- disconnecting and restoring the normal network state
## Command Surface
@@ -23,85 +23,86 @@ node scripts/nordvpn-client.js status
node scripts/nordvpn-client.js install
node scripts/nordvpn-client.js login
node scripts/nordvpn-client.js verify
node scripts/nordvpn-client.js verify --country "Italy"
node scripts/nordvpn-client.js verify --country "Italy" --city "Milan"
node scripts/nordvpn-client.js connect --country "Italy"
node scripts/nordvpn-client.js connect --city "Milan"
node scripts/nordvpn-client.js connect --country "Italy" --city "Milan"
node scripts/nordvpn-client.js verify --country "Germany"
node scripts/nordvpn-client.js verify --country "Japan" --city "Tokyo"
node scripts/nordvpn-client.js connect --country "Germany"
node scripts/nordvpn-client.js connect --country "Japan" --city "Tokyo"
node scripts/nordvpn-client.js disconnect
node scripts/nordvpn-client.js status --debug
```
## Platform Notes
## Backend Model
- Linux:
- uses the official `nordvpn` CLI
- install path follows NordVPN's Linux installer
- token login is supported through `NORDVPN_TOKEN`
- use the official `nordvpn` CLI
- `install` uses the official NordVPN installer
- token login is supported
- macOS:
- preferred backend is NordLynx/WireGuard using `wireguard-go` and `wireguard-tools`
- `install` bootstraps those tools with Homebrew
- equivalent Homebrew command: `brew install wireguard-go wireguard-tools`
- `login` validates `NORDVPN_TOKEN` / `NORDVPN_TOKEN_FILE` for the WireGuard backend
- the generated WireGuard config uses NordVPN DNS directly:
- `103.86.96.100`
- `103.86.99.100`
- before connect, the skill automatically stops Tailscale if it is active
- after disconnect, or after a failed connect, the skill brings Tailscale back up if it stopped it
- `NordVPN.app` can remain installed, but it is only the manual fallback
- use NordLynx/WireGuard through `wireguard-go` and `wireguard-tools`
- `install` bootstraps them with Homebrew
- `login` validates the token for the WireGuard backend
- Tailscale is suspended before connect and resumed after disconnect or failed connect
- `NordVPN.app` may remain installed but is only the manual fallback
## Credentials
Do not store secrets in this skill.
Supported env vars:
- `NORDVPN_TOKEN`
- `NORDVPN_USERNAME`
- `NORDVPN_PASSWORD`
Optional credential file env vars:
- `NORDVPN_TOKEN_FILE`
- `NORDVPN_PASSWORD_FILE`
Default OpenClaw credential paths:
- token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt`
- password: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/password.txt`
## Verification Behavior
Supported env vars:
`status`, `verify`, and `connect` report machine-readable JSON including:
- `NORDVPN_TOKEN`
- `NORDVPN_TOKEN_FILE`
- `NORDVPN_USERNAME`
- `NORDVPN_PASSWORD`
- `NORDVPN_PASSWORD_FILE`
- platform
- install state
- control mode (`cli`, `wireguard`, `app-manual`)
- auth state
- connection state
- requested target
- public IP lookup and geolocation
## macOS Requirements
Use this skill first, then run the follow-up task under the active VPN session.
Use `verify` when you want an explicit post-connect location check without changing VPN state.
Automated macOS connects require all of:
## macOS Quick Start
- `wireguard-go`
- `wireguard-tools`
- `NORDVPN_TOKEN` or the default token file
- non-interactive `sudo` for the installed helper script:
- `~/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh`
For an automated macOS flow:
Exact `visudo` rule for the installed OpenClaw skill:
1. `node scripts/nordvpn-client.js install`
2. put your token in `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt` or set `NORDVPN_TOKEN` / `NORDVPN_TOKEN_FILE`
3. `node scripts/nordvpn-client.js login`
4. `node scripts/nordvpn-client.js connect --country "Italy"` or `--city "Milan"`
5. `node scripts/nordvpn-client.js verify`
```sudoers
stefano ALL=(root) NOPASSWD: /Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh probe, /Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh up, /Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh down
```
## Known Boundaries
## Agent Guidance
- Linux country/city connect remains whatever the official `nordvpn` CLI supports.
- macOS automated connects require all of:
- `NORDVPN_TOKEN` or `NORDVPN_TOKEN_FILE`
- `wireguard-go`
- `wireguard-tools`
- non-interactive `sudo` for `~/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh`
- On macOS, Tailscale is intentionally suspended during an automated NordVPN session and resumed afterward.
- `NordVPN.app` login on macOS is not reused by the WireGuard backend.
- The Homebrew `nordvpn` app does not need to be uninstalled. It can coexist with the WireGuard backend.
- run `status` first when the machine state is unclear
- on macOS, if tooling is missing, run `install`
- if auth is unclear, run `login`
- use `connect` before location-sensitive skills such as `web-automation`
- use `verify` after connect when you need an explicit location check
- use `disconnect` after the follow-up task
## Output Rules
- normal JSON output redacts local path metadata
- use `--debug` only when deeper troubleshooting requires internal local paths and helper/config metadata
## Troubleshooting Cues
- `Invalid authorization header`:
- token file exists but the token is invalid; replace the token and rerun `login`
- `sudoReady: false`:
- the helper is not allowed in sudoers; add the `visudo` rule above
- connect succeeds but final state looks inconsistent:
- rely on the verified public IP/location first
- then inspect `status --debug`
- disconnect should leave:
- normal public IP restored
- no active WireGuard state
- Tailscale resumed if the skill suspended it
For full operator setup and troubleshooting, see:
- `docs/nordvpn-client.md`