From e6dccb56564dd2d3a6f131cf279e769f7d7846c6 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Thu, 12 Mar 2026 02:45:21 -0500 Subject: [PATCH] docs: expand nordvpn client setup and troubleshooting --- docs/nordvpn-client.md | 394 +++++++++++++++--- .../2026-03-12-nordvpn-client-docs-refresh.md | 76 ++++ skills/nordvpn-client/SKILL.md | 135 +++--- 3 files changed, 476 insertions(+), 129 deletions(-) create mode 100644 docs/plans/2026-03-12-nordvpn-client-docs-refresh.md diff --git a/docs/nordvpn-client.md b/docs/nordvpn-client.md index 6da427c..5ae1cdb 100644 --- a/docs/nordvpn-client.md +++ b/docs/nordvpn-client.md @@ -2,14 +2,21 @@ Cross-platform NordVPN lifecycle skill for macOS and Linux. -## What it does +## Overview -- Probes whether NordVPN is already installed or automation-ready -- Bootstraps the required backend if missing -- Handles login/bootstrap -- Connects to a country or city target -- Disconnects and reports status -- Verifies public IP and geolocation after connect +`nordvpn-client` is the operator-facing VPN control skill for OpenClaw. It can: + +- detect whether the host is ready for NordVPN automation +- install or bootstrap the required backend +- validate auth +- 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 @@ -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" --city "Milan" 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 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 ` - ## Credentials -Supported env vars: +Supported inputs: - `NORDVPN_TOKEN` - `NORDVPN_TOKEN_FILE` @@ -68,34 +44,328 @@ Supported env vars: - `NORDVPN_PASSWORD` - `NORDVPN_PASSWORD_FILE` -Do not put secrets in the skill docs or repo. - Default OpenClaw credential paths: - token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.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' '' > ~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt +chmod 600 ~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt +``` -- platform -- install state -- control mode (`cli`, `wireguard`, `app-manual`) -- auth state -- connection state -- requested target -- public IP / geolocation lookup +Do not commit secrets into the repo or the skill docs. -After `connect`, the intended workflow is: +## Platform Backends -1. `nordvpn-client connect ...` -2. `nordvpn-client verify ...` if an explicit location check is needed -3. run the follow-up task such as `web-automation` +### macOS -## Limitations +Current macOS backend: -- Linux behavior still depends on the official `nordvpn` CLI. -- macOS automated connects require token-based WireGuard setup; GUI-app login alone is insufficient. -- macOS automated connects intentionally suspend Tailscale for the duration of the NordVPN session. -- The Homebrew `nordvpn` app does not need to be uninstalled. +- NordLynx/WireGuard +- `wireguard-go` +- `wireguard-tools` +- 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 diff --git a/docs/plans/2026-03-12-nordvpn-client-docs-refresh.md b/docs/plans/2026-03-12-nordvpn-client-docs-refresh.md new file mode 100644 index 0000000..7b33108 --- /dev/null +++ b/docs/plans/2026-03-12-nordvpn-client-docs-refresh.md @@ -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` diff --git a/skills/nordvpn-client/SKILL.md b/skills/nordvpn-client/SKILL.md index 4798a55..c96832f 100644 --- a/skills/nordvpn-client/SKILL.md +++ b/skills/nordvpn-client/SKILL.md @@ -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`