docs: expand nordvpn client setup and troubleshooting
This commit is contained in:
Stefano Fiorini
@@ -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 <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' '<your-nordvpn-token>' > ~/.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
|
||||
|
||||
76
docs/plans/2026-03-12-nordvpn-client-docs-refresh.md
Normal file
76
docs/plans/2026-03-12-nordvpn-client-docs-refresh.md
Normal 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`
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user