stef-openclaw-skills/skills/nordvpn-client/SKILL.md

name, description

name	description
nordvpn-client	Use when managing NordVPN on macOS or Linux, including install/bootstrap, login, connect, disconnect, status checks, or verifying a VPN location before running another skill.

NordVPN Client

Cross-platform NordVPN lifecycle management for macOS and Linux hosts.

Use This Skill For

• 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

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 "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

Backend Model

• Linux:
  • use the official nordvpn CLI
  • install uses the official NordVPN installer
  • token login is supported
• macOS:
  • use NordLynx/WireGuard through wireguard-go and wireguard-tools
  • install bootstraps them with Homebrew
  • login validates the token for the WireGuard backend
  • the generated WireGuard config stays free of DNS = ...
  • connect now requires a bounded persistence gate plus a verified exit before success is declared
  • the skill snapshots and applies NordVPN DNS only to eligible physical services while connected
  • NordVPN DNS is applied only after the tunnel remains up, the final liveness check still shows the requested exit, and system hostname resolution still works afterward
  • disconnect restores the saved DNS/search-domain state even if the tunnel state is stale
  • Tailscale is suspended before connect and resumed after disconnect or failed connect
  • the skill writes a short-lived Tailscale suppression marker during VPN connect so host watchdogs do not immediately re-run tailscale up
  • NordVPN.app may remain installed but is only the manual fallback

Credentials

Default OpenClaw credential paths:

• token: ~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt
• password: ~/.openclaw/workspace/.clawdbot/credentials/nordvpn/password.txt

Supported env vars:

• NORDVPN_TOKEN
• NORDVPN_TOKEN_FILE
• NORDVPN_USERNAME
• NORDVPN_PASSWORD
• NORDVPN_PASSWORD_FILE

macOS Requirements

Automated macOS connects require all of:

• 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

Exact visudo rule for the installed OpenClaw skill:

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

Operational note:

• the persistence gate reuses the already-allowed probe action to confirm the live utun* WireGuard runtime and does not require extra sudoers actions beyond probe, up, and down

Agent Guidance

• 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
• if connect fails its persistence or final verification gate, treat that as a safe rollback, not a partial success

Output Rules

• normal JSON output redacts local path metadata and helper-hardening diagnostics
• 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
• verified: true but persistence.stable: false should not happen anymore; if it does, the skill should roll back instead of pinning DNS
• 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