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

394
docs/nordvpn-client.md
View File

@@ -2,14 +2,21 @@
Cross-platform NordVPN lifecycle skill for macOS and Linux. Cross-platform NordVPN lifecycle skill for macOS and Linux.
## What it does ## Overview
- Probes whether NordVPN is already installed or automation-ready `nordvpn-client` is the operator-facing VPN control skill for OpenClaw. It can:
- Bootstraps the required backend if missing
- Handles login/bootstrap - detect whether the host is ready for NordVPN automation
- Connects to a country or city target - install or bootstrap the required backend
- Disconnects and reports status - validate auth
- Verifies public IP and geolocation after connect - connect to a target country or city
- verify the public exit location
- disconnect and restore normal local networking state
The skill uses different backends by platform:
- Linux: official `nordvpn` CLI
- macOS: NordLynx/WireGuard with `wireguard-go` and `wireguard-tools`
## Commands ## Commands
@@ -21,46 +28,15 @@ node skills/nordvpn-client/scripts/nordvpn-client.js verify
node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Italy" node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Italy"
node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Italy" --city "Milan" node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Italy" --city "Milan"
node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Italy" node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Italy"
node skills/nordvpn-client/scripts/nordvpn-client.js connect --city "Milan" node skills/nordvpn-client/scripts/nordvpn-client.js connect --city "Tokyo"
node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Japan" --city "Tokyo"
node skills/nordvpn-client/scripts/nordvpn-client.js disconnect node skills/nordvpn-client/scripts/nordvpn-client.js disconnect
node skills/nordvpn-client/scripts/nordvpn-client.js status --debug
``` ```
## Platform behavior
### macOS
- preferred backend: NordLynx/WireGuard
- install path: `brew install wireguard-go wireguard-tools`
- automation requirements:
- `NORDVPN_TOKEN` or `NORDVPN_TOKEN_FILE`
- `wireguard-go`
- `wireguard-tools`
- non-interactive `sudo` for `~/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh`
- the macOS WireGuard config uses NordVPN DNS directly:
- `103.86.96.100`
- `103.86.99.100`
- before connect, the skill automatically suspends Tailscale if it is active
- after disconnect, or after a failed connect, the skill brings Tailscale back up if it suspended it
- `NordVPN.app` may stay installed but is only the manual fallback
- the app login is not reused by the automated WireGuard backend
Quick start:
1. `node skills/nordvpn-client/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 skills/nordvpn-client/scripts/nordvpn-client.js login`
4. `node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Italy"` or `--city "Milan"`
5. `node skills/nordvpn-client/scripts/nordvpn-client.js verify`
### Linux
- install path follows NordVPN's official installer script
- primary control path is the official `nordvpn` CLI
- token login is supported through `nordvpn login --token <token>`
## Credentials ## Credentials
Supported env vars: Supported inputs:
- `NORDVPN_TOKEN` - `NORDVPN_TOKEN`
- `NORDVPN_TOKEN_FILE` - `NORDVPN_TOKEN_FILE`
@@ -68,34 +44,328 @@ Supported env vars:
- `NORDVPN_PASSWORD` - `NORDVPN_PASSWORD`
- `NORDVPN_PASSWORD_FILE` - `NORDVPN_PASSWORD_FILE`
Do not put secrets in the skill docs or repo.
Default OpenClaw credential paths: Default OpenClaw credential paths:
- token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt` - token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt`
- password: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/password.txt` - password: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/password.txt`
## Verification model Recommended setup on macOS is a token file with strict permissions:
`status`, `verify`, and `connect` emit JSON suitable for agent use: ```bash
mkdir -p ~/.openclaw/workspace/.clawdbot/credentials/nordvpn
chmod 700 ~/.openclaw/workspace/.clawdbot/credentials/nordvpn
printf '%s\n' '<your-nordvpn-token>' > ~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt
chmod 600 ~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt
```
- platform Do not commit secrets into the repo or the skill docs.
- install state
- control mode (`cli`, `wireguard`, `app-manual`)
- auth state
- connection state
- requested target
- public IP / geolocation lookup
After `connect`, the intended workflow is: ## Platform Backends
1. `nordvpn-client connect ...` ### macOS
2. `nordvpn-client verify ...` if an explicit location check is needed
3. run the follow-up task such as `web-automation`
## Limitations Current macOS backend:
- Linux behavior still depends on the official `nordvpn` CLI. - NordLynx/WireGuard
- macOS automated connects require token-based WireGuard setup; GUI-app login alone is insufficient. - `wireguard-go`
- macOS automated connects intentionally suspend Tailscale for the duration of the NordVPN session. - `wireguard-tools`
- The Homebrew `nordvpn` app does not need to be uninstalled. - NordVPN DNS in the generated WireGuard config:
- `103.86.96.100`
- `103.86.99.100`
Important behavior:
- `NordVPN.app` may remain installed, but the automated backend does not reuse app login state.
- The skill automatically suspends Tailscale before connect if Tailscale is active.
- The skill resumes Tailscale after disconnect, or after a failed connect, if it stopped it.
- The Homebrew NordVPN app does not need to be uninstalled.
### Linux
Current Linux backend:
- official `nordvpn` CLI
- official NordVPN installer
- token login through `nordvpn login --token ...`
## Install / Bootstrap
### macOS
Bootstrap the automation backend:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js install
```
Equivalent Homebrew command:
```bash
brew install wireguard-go wireguard-tools
```
What `install` does on macOS:
- checks whether `wireguard-go` is present
- checks whether `wg` and `wg-quick` are present
- installs missing packages through Homebrew
### Linux
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js install
```
What `install` does on Linux:
- downloads NordVPN’s official installer script
- runs it
- leaves subsequent login/connect to the official `nordvpn` CLI
## macOS sudoers Setup
Automated macOS connect/disconnect requires passwordless `sudo` for the helper script that invokes `wg-quick`.
Installed OpenClaw helper path:
```text
/Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh
```
Edit sudoers safely:
```bash
sudo visudo
```
Add this exact rule:
```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
```
If you run the repo copy directly instead of the installed OpenClaw skill, adjust the helper path accordingly.
## Common Flows
### Status
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js status
```
Use this first to answer:
- is the correct backend available?
- is the token visible?
- is `sudoReady` true?
- is the machine currently connected?
### Login
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js login
```
On macOS this validates the token and populates the local auth cache. It does not connect the VPN.
### Connect
Country:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Germany"
```
City:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Japan" --city "Tokyo"
```
Expected macOS behavior:
- stop Tailscale if active
- select a NordVPN server for the target
- bring up the WireGuard tunnel
- verify the public exit location
- return JSON describing the chosen server and final verified location
### Verify
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Germany"
```
Use this after connect if you want an explicit location check without changing VPN state.
### Disconnect
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js disconnect
```
Expected macOS behavior:
- attempt `wg-quick down` whenever there is active or residual NordVPN WireGuard state
- remove stale local NordVPN state files after teardown
- resume Tailscale if the skill had suspended it
## Output Model
Normal JSON is redacted by default.
Redacted fields in normal mode:
- `cliPath`
- `appPath`
- `wireguard.configPath`
- `wireguard.helperPath`
- `wireguard.authCache.tokenSource`
Operational fields preserved in normal mode:
- `connected`
- `wireguard.active`
- `wireguard.endpoint`
- `requestedTarget`
- `verification`
- public IP and location
For deeper troubleshooting, use:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js status --debug
```
`--debug` keeps the internal local paths and other low-level metadata in the JSON output.
## Troubleshooting
### `Invalid authorization header`
Meaning:
- the token file was found
- the token value is not valid for NordVPN’s API
Actions:
1. generate a fresh NordVPN access token
2. replace the contents of `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt`
3. run:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js login
```
### `sudoReady: false`
Meaning:
- the helper script is present
- the agent cannot run `wg-quick` non-interactively
Actions:
1. add the `visudo` rule shown above
2. rerun:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js status
```
Expected:
- `wireguard.sudoReady: true`
### WireGuard tools missing
Meaning:
- macOS backend is selected
- `wireguard-go`, `wg`, or `wg-quick` is missing
Actions:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js install
```
or:
```bash
brew install wireguard-go wireguard-tools
```
### Tailscale interaction
Expected behavior on macOS:
- Tailscale is suspended before the NordVPN connect
- Tailscale is resumed after disconnect or failed connect
If a connect succeeds but later traffic is wrong, check:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js status
/opt/homebrew/bin/tailscale status --json
```
Look for:
- `connected: true` and a foreign exit IP while NordVPN is up
- `connected: false` and Texas/Garland IP after disconnect
### Status says disconnected after a verified connect
This was a previous macOS false-negative path and is now normalized in the connect response.
Current expectation:
- if `connect` verifies the target location successfully
- the returned `state` snapshot should also show:
- `connected: true`
- `wireguard.active: true`
If that regresses, capture:
- `connect` JSON
- `verify` JSON
- `status --debug` JSON
### Disconnect says “no active connection” but traffic is still foreign
The current macOS disconnect path now treats residual WireGuard state as sufficient reason to attempt teardown.
Safe operator check:
```bash
node skills/nordvpn-client/scripts/nordvpn-client.js disconnect
node skills/nordvpn-client/scripts/nordvpn-client.js verify
```
Expected after a good disconnect:
- Texas/Garland public IP again
- `wireguard.configPath: null` in normal status output
- `wireguard.lastConnection: null`
If that regresses, capture:
- `disconnect` JSON
- `verify` JSON
- `status --debug` JSON
## Recommended Agent Workflow
For VPN-routed work:
1. `status`
2. `install` if backend tooling is missing
3. `login` if token validation has not happened yet
4. `connect --country ...` or `connect --country ... --city ...`
5. `verify`
6. run the follow-up skill such as `web-automation`
7. `disconnect`
8. `verify` again if you need proof the machine returned to the normal exit path

76
docs/plans/2026-03-12-nordvpn-client-docs-refresh.md Normal file
View File

@@ -0,0 +1,76 @@
# NordVPN Client Docs Refresh Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Refresh the `nordvpn-client` documentation so operators and the OpenClaw agent have complete, accurate setup and troubleshooting guidance for the current macOS and Linux backends.
**Architecture:** Expand the canonical repo doc into a full operator guide, tighten the agent-facing `SKILL.md` to match the current behavior, and lightly update summary docs only if their current one-line descriptions are materially incomplete. Sync the updated `SKILL.md` into the installed OpenClaw workspace copy so runtime guidance matches the repo.
**Tech Stack:** Markdown docs, local repo skill docs, OpenClaw workspace skill sync
---
### Task 1: Refresh canonical operator documentation
**Files:**
- Modify: `docs/nordvpn-client.md`
**Step 1: Rewrite the doc structure**
- Add sections for overview, platform backends, prerequisites, credential paths, install/bootstrap, macOS sudoers setup, command flows, output model, and troubleshooting.
**Step 2: Add exact operator setup details**
- Include the exact `visudo` entry for the helper script.
- Document default token/password file locations.
- Document Homebrew install commands for macOS tooling.
**Step 3: Add safe troubleshooting guidance**
- Include only safe operator procedures from the debugging work:
- invalid token handling
- `sudoReady: false`
- Tailscale suspend/resume expectations
- what normal redacted output includes
- how to use `--debug` when deeper inspection is needed
### Task 2: Refresh agent-facing skill documentation
**Files:**
- Modify: `skills/nordvpn-client/SKILL.md`
- Sync: `/Users/stefano/.openclaw/workspace/skills/nordvpn-client/SKILL.md`
**Step 1: Tighten the skill instructions**
- Keep the doc shorter than the canonical operator guide.
- Ensure it explicitly covers the default credential paths, macOS sudoers requirement, Tailscale suspend/resume behavior, and `--debug` usage.
**Step 2: Sync installed OpenClaw copy**
- Copy the updated repo `SKILL.md` into the installed workspace skill path.
### Task 3: Update summary docs if needed
**Files:**
- Check: `README.md`
- Check: `docs/README.md`
- Modify only if current summary text is materially missing the current backend model.
**Step 1: Review summary descriptions**
- Confirm whether the one-line descriptions already adequately describe Linux CLI + macOS NordLynx/WireGuard.
**Step 2: Update only if necessary**
- Avoid churn if the existing summaries are already sufficient.
### Task 4: Verify and publish
**Files:**
- Verify: `docs/nordvpn-client.md`
- Verify: `skills/nordvpn-client/SKILL.md`
- Verify: `/Users/stefano/.openclaw/workspace/skills/nordvpn-client/SKILL.md`
**Step 1: Run doc verification checks**
- Run: `rg -n "sudoers|visudo|--debug|Tailscale|token.txt|wireguard-helper" docs/nordvpn-client.md skills/nordvpn-client/SKILL.md`
- Expected: all required topics present
**Step 2: Confirm installed workspace skill matches repo skill**
- Run: `cmp skills/nordvpn-client/SKILL.md /Users/stefano/.openclaw/workspace/skills/nordvpn-client/SKILL.md`
- Expected: no output
**Step 3: Commit and push**
- Commit message: `docs: expand nordvpn client setup and troubleshooting`

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. 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 - probing whether NordVPN automation is ready
- Bootstrapping the required NordVPN backend if it is missing - bootstrapping missing backend dependencies
- Logging in through the Linux CLI or validating a NordVPN token for the macOS WireGuard backend - validating auth
- Connecting to a country or city before a follow-up action such as `web-automation` - connecting to a country or city
- Disconnecting and checking VPN status - verifying the public exit location
- Verifying public IP and geolocation after connect - disconnecting and restoring the normal network state
## Command Surface ## Command Surface
@@ -23,85 +23,86 @@ node scripts/nordvpn-client.js status
node scripts/nordvpn-client.js install node scripts/nordvpn-client.js install
node scripts/nordvpn-client.js login node scripts/nordvpn-client.js login
node scripts/nordvpn-client.js verify node scripts/nordvpn-client.js verify
node scripts/nordvpn-client.js verify --country "Italy" node scripts/nordvpn-client.js verify --country "Germany"
node scripts/nordvpn-client.js verify --country "Italy" --city "Milan" node scripts/nordvpn-client.js verify --country "Japan" --city "Tokyo"
node scripts/nordvpn-client.js connect --country "Italy" node scripts/nordvpn-client.js connect --country "Germany"
node scripts/nordvpn-client.js connect --city "Milan" node scripts/nordvpn-client.js connect --country "Japan" --city "Tokyo"
node scripts/nordvpn-client.js connect --country "Italy" --city "Milan"
node scripts/nordvpn-client.js disconnect node scripts/nordvpn-client.js disconnect
node scripts/nordvpn-client.js status --debug
``` ```
## Platform Notes ## Backend Model
- Linux: - Linux:
- uses the official `nordvpn` CLI - use the official `nordvpn` CLI
- install path follows NordVPN's Linux installer - `install` uses the official NordVPN installer
- token login is supported through `NORDVPN_TOKEN` - token login is supported
- macOS: - macOS:
- preferred backend is NordLynx/WireGuard using `wireguard-go` and `wireguard-tools` - use NordLynx/WireGuard through `wireguard-go` and `wireguard-tools`
- `install` bootstraps those tools with Homebrew - `install` bootstraps them with Homebrew
- equivalent Homebrew command: `brew install wireguard-go wireguard-tools` - `login` validates the token for the WireGuard backend
- `login` validates `NORDVPN_TOKEN` / `NORDVPN_TOKEN_FILE` for the WireGuard backend - Tailscale is suspended before connect and resumed after disconnect or failed connect
- the generated WireGuard config uses NordVPN DNS directly: - `NordVPN.app` may remain installed but is only the manual fallback
- `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
## Credentials ## 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: Default OpenClaw credential paths:
- token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt` - token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt`
- password: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/password.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 ## macOS Requirements
- install state
- control mode (`cli`, `wireguard`, `app-manual`)
- auth state
- connection state
- requested target
- public IP lookup and geolocation
Use this skill first, then run the follow-up task under the active VPN session. Automated macOS connects require all of:
Use `verify` when you want an explicit post-connect location check without changing VPN state.
## 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` ```sudoers
2. put your token in `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt` or set `NORDVPN_TOKEN` / `NORDVPN_TOKEN_FILE` 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
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`
## Known Boundaries ## Agent Guidance
- Linux country/city connect remains whatever the official `nordvpn` CLI supports. - run `status` first when the machine state is unclear
- macOS automated connects require all of: - on macOS, if tooling is missing, run `install`
- `NORDVPN_TOKEN` or `NORDVPN_TOKEN_FILE` - if auth is unclear, run `login`
- `wireguard-go` - use `connect` before location-sensitive skills such as `web-automation`
- `wireguard-tools` - use `verify` after connect when you need an explicit location check
- non-interactive `sudo` for `~/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh` - use `disconnect` after the follow-up task
- 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. ## Output Rules
- The Homebrew `nordvpn` app does not need to be uninstalled. It can coexist with the WireGuard backend.
- 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`