install-vt-sentinel

name	install-vt-sentinel
description	Install or upgrade VT Sentinel security plugin. Use when the user asks to install, set up, enable, update, or upgrade VT Sentinel, VirusTotal scanning, malware protection, or file security scanning. Handles fresh installs and upgrades from any previous version.
user-invocable	true
metadata	{"openclaw":{"emoji":"🛡️","requires":{"anyBins":["npm","pnpm","yarn","bun"]}}}

Install / Upgrade VT Sentinel Plugin

Step 1: Check current state

exec { "command": "openclaw plugins list 2>/dev/null | grep vt-sentinel" }

Determine the platform:

exec { "command": "uname -s 2>/dev/null || echo Windows" }

Three possible outcomes:

• Not installed → go to Step 2 (fresh install)
• Installed, older version → go to Step 3 (upgrade)
• Installed, already v0.10.0 or newer → tell the user it's up to date and skip remaining steps

To check the installed version:

exec { "command": "node -e \"const p=require(process.env.HOME+'/.openclaw/extensions/openclaw-plugin-vt-sentinel/package.json');console.log(p.version)\" 2>/dev/null || echo unknown" }

On Windows use %USERPROFILE% instead of $HOME.

Step 2: Fresh install

exec { "command": "openclaw plugins install openclaw-plugin-vt-sentinel" }

This downloads the npm package, registers the plugin, loads skills and hooks automatically. No manual configuration needed. Go to Step 4.

Step 3: Upgrade from previous version

The openclaw plugins install command does NOT support in-place upgrade — it fails with "plugin already exists". The upgrade process is:

3a. Remove old extension directory (preserves all user data)

On Linux/macOS:

exec { "command": "rm -rf ~/.openclaw/extensions/openclaw-plugin-vt-sentinel" }

On Windows:

exec { "command": "rmdir /s /q %USERPROFILE%\\.openclaw\\extensions\\openclaw-plugin-vt-sentinel" }

User data is safe — these files live outside the plugin directory and are preserved:

• ~/.openclaw/vt-sentinel-state.json (configuration overrides, onboarding flags)
• ~/.openclaw/vt-sentinel-uploads.log (audit log)
• ~/.openclaw/vt-sentinel-detections.log (audit log)
• ~/.openclaw/vtai-agent-credentials.json (VTAI API credentials)

3b. Clean stale install entry (preserves user config)

After removing the extension directory, openclaw.json still references the old plugin path in plugins.installs, which causes validation errors. Only remove the stale install metadata — user config in plugins.entries (apiKey, etc.) is preserved:

On Linux/macOS:

exec { "command": "node -e \"const fs=require('fs'),p=process.env.HOME+'/.openclaw/openclaw.json';try{const P=(()=>{try{return require('json5').parse}catch{return JSON.parse}})();const c=P(fs.readFileSync(p,'utf8'));if(c.plugins?.installs)delete c.plugins.installs['openclaw-plugin-vt-sentinel'];fs.writeFileSync(p,JSON.stringify(c,null,2));console.log('Config cleaned')}catch(e){console.log('No config to clean: '+e.message)}\"" }

On Windows:

exec { "command": "node -e \"const fs=require('fs'),p=process.env.USERPROFILE+'\\\\.openclaw\\\\openclaw.json';try{const P=(()=>{try{return require('json5').parse}catch{return JSON.parse}})();const c=P(fs.readFileSync(p,'utf8'));if(c.plugins?.installs)delete c.plugins.installs['openclaw-plugin-vt-sentinel'];fs.writeFileSync(p,JSON.stringify(c,null,2));console.log('Config cleaned')}catch(e){console.log('No config to clean: '+e.message)}\"" }

3c. Install new version

exec { "command": "openclaw plugins install openclaw-plugin-vt-sentinel" }

If this fails on Windows with spawn EINVAL, use the manual method:

exec { "command": "cd %TEMP% && npm pack openclaw-plugin-vt-sentinel && mkdir %USERPROFILE%\\.openclaw\\extensions\\openclaw-plugin-vt-sentinel && tar xzf openclaw-plugin-vt-sentinel-0.10.0.tgz -C %USERPROFILE%\\.openclaw\\extensions\\openclaw-plugin-vt-sentinel --strip-components=1 && cd %USERPROFILE%\\.openclaw\\extensions\\openclaw-plugin-vt-sentinel && npm install --omit=dev" }

Step 4: Restart the gateway

The plugin won't be active until the gateway restarts. Detect the platform and use the appropriate command:

Linux:

exec { "command": "systemctl --user restart openclaw-gateway.service" }

macOS:

exec { "command": "openclaw gateway restart" }

Windows:

exec { "command": "openclaw gateway restart" }

Step 5: Verify

After restart, check that the plugin loaded correctly and shows 9 tools:

exec { "command": "openclaw plugins list 2>/dev/null | grep vt-sentinel" }

Step 6: Inform the user

Tell the user:

1. VT Sentinel is installed and active (mention if this was an upgrade, and from which version).
2. No API key needed — it auto-registers with VirusTotal's AI API (zero-config).
3. Optionally, they can add their own VirusTotal API key for higher rate limits via openclaw plugins config openclaw-plugin-vt-sentinel apiKey <key>.

VT Sentinel provides:

• vt_scan_file — Full file scan (AV + AI Code Insight)
• vt_check_hash — Quick hash lookup
• vt_upload_consent — Consent for sensitive file uploads
• vt_sentinel_status — View current config, watched dirs, protection status
• vt_sentinel_configure — Change settings at runtime (presets, notify level, block mode)
• vt_sentinel_reset_policy — Reset to defaults
• vt_sentinel_help — Quick-start guide and privacy info
• vt_sentinel_update — Check for updates and get upgrade instructions
• vt_sentinel_re_register — Re-register agent identity with VTAI
• Automatic scanning of downloaded/created files
• Active blocking of malicious file execution and dangerous command patterns

Troubleshooting

If openclaw plugins install fails:

• Check internet connectivity: exec { "command": "npm ping" }
• Try with verbose output: exec { "command": "openclaw plugins install openclaw-plugin-vt-sentinel --verbose" }
• On Windows, if spawn EINVAL error occurs, use the manual method from Step 3b

Constraints

• Do NOT modify openclaw.json manually — openclaw plugins install handles everything
• If the user reports the plugin is blocked, check plugins.deny in their openclaw.json