mateclaw-openclaw-plugin 0.1.2 → 0.1.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 MateClaw
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 MateClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,100 +1,156 @@
-# mateclaw-openclaw-plugin
-
-[![npm version](https://img.shields.io/npm/v/mateclaw-openclaw-plugin?label=npm)](https://www.npmjs.com/package/mateclaw-openclaw-plugin)
-[![node](https://img.shields.io/node/v/mateclaw-openclaw-plugin)](https://www.npmjs.com/package/mateclaw-openclaw-plugin)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-
-This package provides a folotoy-style one-command local setup for MateClaw demos:
-
+# mateclaw-openclaw-plugin
+
+[![npm version](https://img.shields.io/npm/v/mateclaw-openclaw-plugin?label=npm)](https://www.npmjs.com/package/mateclaw-openclaw-plugin)
+[![node](https://img.shields.io/node/v/mateclaw-openclaw-plugin)](https://www.npmjs.com/package/mateclaw-openclaw-plugin)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+This package provides a one-command local setup for MateClaw app-only flow:
+
 - `doctor` checks OpenClaw, gateway, token, identity, LAN, and connector port
-- `install` runs `doctor + auto-fix + optional gateway restart + connector start`
-- connector outputs QR code and keeps app chat in the same gateway session
-
-## Customer one-command flow
-
+- `install` runs `doctor + auto-fix + optional gateway restart + connector service start`
+- by default connector runs in background service, so CMD can be closed after install
+
+## Customer one-command flow
+
 Published package usage:
 
 ```bash
-npx -y mateclaw-openclaw-plugin install --chat-mode gateway-session --session-key agent:main:main
-```
-
-Local repo usage:
-
-```bash
-cd mateclaw-openclaw-plugin
-npm install
-node ./src/cli.mjs install --chat-mode gateway-session --session-key agent:main:main
+npx -y mateclaw-openclaw-plugin install
 ```
 
-After startup:
-
-1. Scan the OpenClaw-side QR code shown by the installer in MateClaw app.
-2. Start text chat directly in app.
-3. Optional desktop same-session view:
-`http://127.0.0.1:18789/chat?session=agent%3Amain%3Amain`
-
-## What `install` auto-handles
+This preset command auto-uses:
+- `chat-mode=gateway-session`
+- `session-key=agent:main:main`
+- built-in reverse tunnel
+- tunnel target `xxx@xxx`
+- public bind URL `https://xxx`
 
-- Checks OpenClaw CLI version and gateway health/status
-- Checks and repairs `~/.openclaw/openclaw.json` (`gateway.mode`, `gateway.auth.mode`, token/password)
-- Auto-backs up existing `openclaw.json` before writing
-- Checks and auto-creates device identity (`~/.openclaw/identity/device.json`) when missing
-- Checks and syncs device auth token (`~/.openclaw/identity/device-auth.json`) when missing
-- Auto-selects current LAN IPv4
-- Auto-switches connector port when preferred port is occupied
-- Optionally restarts gateway (`openclaw gateway restart`)
-- Starts connector and prints binding QR
+You will be prompted for tunnel password with hidden input.
+If you only want LAN (no tunnel): `npx -y mateclaw-openclaw-plugin install --lan-only`
 
-## Commands
+Background service commands:
 
 ```bash
+npx -y mateclaw-openclaw-plugin service-status
+npx -y mateclaw-openclaw-plugin service-stop
+```
+
+Local repo usage:
+
+```bash
+cd mateclaw-openclaw-plugin
+npm install
+node ./src/cli.mjs install --chat-mode gateway-session --session-key agent:main:main
+```
+
+After startup:
+
+1. Scan the OpenClaw-side QR code shown by the installer in MateClaw app.
+2. Start text chat directly in app.
+3. Optional desktop same-session view:
+`http://127.0.0.1:18789/chat?session=agent%3Amain%3Amain`
+
+## What `install` auto-handles
+
+- Checks OpenClaw CLI version and gateway health/status
+- Checks and repairs `~/.openclaw/openclaw.json` (`gateway.mode`, `gateway.auth.mode`, token/password)
+- Auto-backs up existing `openclaw.json` before writing
+- Checks and auto-creates device identity (`~/.openclaw/identity/device.json`) when missing
+- Checks and syncs device auth token (`~/.openclaw/identity/device-auth.json`) when missing
+- Auto-selects current LAN IPv4
+- Auto-switches connector port when preferred port is occupied
+- Optionally restarts gateway (`openclaw gateway restart`)
+- Starts connector and prints binding QR
+
+## Commands
+
+```bash
 node ./src/cli.mjs doctor
 node ./src/cli.mjs install
 node ./src/cli.mjs connect
 node ./src/cli.mjs login install   # alias of install
+node ./src/cli.mjs service-status
+node ./src/cli.mjs service-stop
 ```
-
-## Useful options
-
-```bash
-node ./src/cli.mjs install \
-  --openclaw-url http://127.0.0.1:18789 \
-  --chat-mode gateway-session \
-  --session-key agent:main:main \
-  --port 18890
-```
-
-- `--openclaw-bin <cmd>`: override OpenClaw CLI command
-- `--config-path <path>`: override openclaw config path
+
+## Useful options
+
+```bash
+node ./src/cli.mjs install \
+  --openclaw-url http://127.0.0.1:18789 \
+  --chat-mode gateway-session \
+  --session-key agent:main:main \
+  --port 18890
+```
+
+- `--openclaw-bin <cmd>`: override OpenClaw CLI command
+- `--config-path <path>`: override openclaw config path
 - `--skip-gateway-restart`: skip `openclaw gateway restart`
 - `--skip-connector`: only run setup, do not start connector
+- `--foreground`: run connector in current CMD (do not use background service)
 - `--dry-run`: print planned fixes without writing files
 - `--lan-host <ip>`: pin LAN IP manually
+- `--public-base-url <url>`: override QR baseUrl with public URL
+- `--tunnel`: enable reverse tunnel
+- `--lan-only`: disable tunnel and force LAN-only QR/baseUrl
+- `--tunnel-client <builtin|ssh|nssh>`: choose tunnel client (default: `builtin`)
+- `--tunnel-user / --tunnel-host`: tunnel account and host
+- `--tunnel-password`: required by `builtin` and `nssh`
 
-## Development scripts
-
-```bash
-npm run doctor
-npm run install:local
-npm run connect
-npm run check:publish
-npm run pack:dry-run
-npm run publish:dry-run
-```
+## Intranet tunnel (internal provider)
 
-## Publish
+Example (one-command, no extra tunnel client install, use `builtin`):
 
 ```bash
-npm login
-npm run check:publish
-npm run publish:dry-run
-npm run publish:public
+node ./src/cli.mjs install \
+  --chat-mode gateway-session \
+  --session-key agent:main:main \
+  --tunnel \
+  --tunnel-client builtin \
+  --tunnel-user xxx \
+  --tunnel-host xxx \
+  --tunnel-remote-port 80 \
+  --public-base-url https://xxx
 ```
 
-Use Automation Token (no OTP on publish):
+If `--tunnel-password` is omitted, CLI will ask for hidden password input interactively.
+
+Alternative external client forms:
 
 ```bash
-# PowerShell
-$env:NPM_TOKEN = "npm_xxx_your_automation_token"
-npm run publish:token
+ssh -R 80:127.0.0.1:18890 xxx@xxx
+nssh -R 80:127.0.0.1:18890 xxx@xxx --passwd <password>
 ```
+
+## Security note (next phase)
+
+Current simple mode still needs customer-side tunnel credentials.
+Planned upgrade is backend-issued short-lived tunnel tickets, so no long-term shared password is exposed to customers.
+
+## Development scripts
+
+```bash
+npm run doctor
+npm run install:local
+npm run connect
+npm run check:publish
+npm run pack:dry-run
+npm run publish:dry-run
+```
+
+## Publish
+
+```bash
+npm login
+npm run check:publish
+npm run publish:dry-run
+npm run publish:public
+```
+
+Use Automation Token (no OTP on publish):
+
+```bash
+# PowerShell
+$env:NPM_TOKEN = "npm_xxx_your_automation_token"
+npm run publish:token
+```

package/package.json

@@ -1,37 +1,38 @@
-{
-  "name": "mateclaw-openclaw-plugin",
-  "version": "0.1.2",
-  "private": false,
-  "type": "module",
-  "description": "Local OpenClaw connector for MateClaw customer demos",
-  "license": "MIT",
-  "bin": {
-    "mateclaw-openclaw-plugin": "src/cli.mjs"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "doctor": "node ./src/cli.mjs doctor",
-    "install:local": "node ./src/cli.mjs install",
-    "connect": "node ./src/cli.mjs connect",
-    "check:publish": "node ./scripts/prepublish-check.mjs",
-    "pack:dry-run": "npm pack --dry-run",
-    "publish:dry-run": "npm publish --dry-run --access public",
-    "publish:public": "npm publish --access public",
-    "publish:token": "node ./scripts/publish-with-token.mjs",
-    "prepublishOnly": "npm run check:publish"
-  },
-  "dependencies": {
-    "qrcode-terminal": "^0.12.0",
-    "ws": "^8.18.3"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "mateclaw-openclaw-plugin",
+  "version": "0.1.4",
+  "private": false,
+  "type": "module",
+  "description": "Local OpenClaw connector for MateClaw customer demos",
+  "license": "MIT",
+  "bin": {
+    "mateclaw-openclaw-plugin": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "doctor": "node ./src/cli.mjs doctor",
+    "install:local": "node ./src/cli.mjs install",
+    "connect": "node ./src/cli.mjs connect",
+    "check:publish": "node ./scripts/prepublish-check.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "publish:public": "npm publish --access public",
+    "publish:token": "node ./scripts/publish-with-token.mjs",
+    "prepublishOnly": "npm run check:publish"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "ssh2": "^1.17.0",
+    "ws": "^8.18.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.mjs

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 
 import crypto from 'node:crypto';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
-import { URL } from 'node:url';
+import readline from 'node:readline';
+import { URL, fileURLToPath } from 'node:url';
 import qrcode from 'qrcode-terminal';
+import { Client as SshClient } from 'ssh2';
 import { WebSocket } from 'ws';
 
 const DEFAULT_OPENCLAW_URL = 'http://127.0.0.1:18789';
@@ -27,8 +29,18 @@ const DEFAULT_PORT = 18890;
 const DEFAULT_AGENT_ID = 'main';
 const DEFAULT_EXPIRES_MINUTES = 720;
 const DEFAULT_UPSTREAM_TIMEOUT_MS = 180000;
-const PAYLOAD_TYPE = 'mateclaw_local_openclaw_demo';
+const PAYLOAD_TYPE = 'mateclaw_openclaw_plugin';
 const DEFAULT_OPENCLAW_BIN = process.platform === 'win32' ? 'openclaw.cmd' : 'openclaw';
+const DEFAULT_TUNNEL_CLIENT = 'builtin';
+const DEFAULT_TUNNEL_SERVER_PORT = 22;
+const DEFAULT_TUNNEL_REMOTE_PORT = 80;
+const DEFAULT_TUNNEL_LOCAL_HOST = '127.0.0.1';
+const DEFAULT_PRESET_TUNNEL_ENABLED = true;
+const DEFAULT_PRESET_TUNNEL_USER = '6111605006';
+const DEFAULT_PRESET_TUNNEL_HOST = 'gz2.neiwangyun.net';
+const DEFAULT_PRESET_TUNNEL_PASSWORD = 'skg5gm';
+const DEFAULT_PRESET_PUBLIC_BASE_URL = 'https://6hjduygz2.neiwangyun.net';
+const CURRENT_CLI_PATH = fileURLToPath(import.meta.url);
 
 async function main() {
   const rawArgs = process.argv.slice(2);
@@ -37,7 +49,7 @@ async function main() {
 
   switch (resolved.command) {
     case 'connect': {
-      const config = buildConfig(options);
+      const config = await buildConfig(options);
       await startConnector(config);
       return;
     }
@@ -49,6 +61,14 @@ async function main() {
       await runDoctor(options);
       return;
     }
+    case 'service-stop': {
+      await runServiceStop();
+      return;
+    }
+    case 'service-status': {
+      await runServiceStatus();
+      return;
+    }
     case 'help':
       printHelp();
       return;
@@ -79,8 +99,10 @@ function printHelp() {
   console.log('');
   console.log('Commands:');
   console.log('  install              One-command setup: check OpenClaw, auto-fix config, restart gateway, start connector');
-  console.log('  login install        Alias of install (for folotoy-like UX)');
+  console.log('  login install        Alias of install');
   console.log('  connect              Start connector directly (no config repair)');
+  console.log('  service-stop         Stop background connector service started by install');
+  console.log('  service-status       Show background connector service status');
   console.log('  doctor               Check OpenClaw and local config health');
   console.log('');
   console.log('Shared options (connect/install):');
@@ -97,13 +119,28 @@ function printHelp() {
   console.log('  --upstream-timeout-ms <ms>  Upstream OpenClaw request timeout');
   console.log('  --chat-mode <mode>      gateway-session | http-proxy');
   console.log('  --session-key <key>     Fixed Gateway session key (default: agent:<agent-id>:main)');
+  console.log('  --public-base-url <url> Override QR baseUrl with a public URL');
+  console.log('  --tunnel                Enable reverse tunnel (ssh/nssh)');
+  console.log('  --lan-only              Force LAN-only mode (disable tunnel/public URL)');
+  console.log('  --tunnel-client <name>  builtin | ssh | nssh (default: builtin)');
+  console.log('                           builtin uses embedded SSH reverse tunnel (no nssh install needed)');
+  console.log('  --tunnel-bin <cmd>      Tunnel client command path');
+  console.log('  --tunnel-user <user>    Tunnel account user');
+  console.log('  --tunnel-host <host>    Tunnel server host');
+  console.log('  --tunnel-server-port <n> SSH service port (default: 22)');
+  console.log('  --tunnel-remote-port <n> Public exposed port (default: 80)');
+  console.log('  --tunnel-password <pwd> tunnel password for builtin/nssh (or set MATECLAW_TUNNEL_PASSWORD)');
   console.log('');
   console.log('Install/Doctor options:');
   console.log('  --openclaw-bin <cmd>    OpenClaw CLI command (default: openclaw/openclaw.cmd)');
   console.log('  --config-path <path>    Override openclaw.json path');
   console.log('  --skip-gateway-restart  Skip openclaw gateway restart after config updates');
   console.log('  --skip-connector        Only setup config, do not start local connector');
+  console.log('  --foreground            Keep connector in current CMD (no background service)');
   console.log('  --dry-run               Validate and print changes without writing files');
+  console.log('');
+  console.log('Quick start (preset tunnel defaults + hidden password prompt):');
+  console.log('  npx -y mateclaw-openclaw-plugin install');
 }
 
 function parseArgs(args) {
@@ -224,6 +261,7 @@ function runOpenClawCommand(bin, args, timeoutMs = 20000) {
       encoding: 'utf8',
       timeout: timeoutMs,
       shell: process.platform === 'win32',
+      windowsHide: true,
     });
     const stdout = `${result.stdout || ''}`.trim();
     const stderr = `${result.stderr || ''}`.trim();
@@ -263,6 +301,41 @@ function summarizeCommandFailure(result) {
   return detail || `exit code ${result.status}`;
 }
 
+function isCommandAvailable(commandName) {
+  const name = `${commandName || ''}`.trim();
+  if (!name) return false;
+  const probeTool = process.platform === 'win32' ? 'where' : 'which';
+  const probe = runOpenClawCommand(probeTool, [name], 8000);
+  return probe.ok && `${probe.stdout || ''}`.trim().length > 0;
+}
+
+async function readSecretFromPrompt(promptText) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return '';
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+  const originalWrite = rl._writeToOutput;
+  rl._writeToOutput = function writeMaskedOutput(stringToWrite) {
+    if (rl.stdoutMuted) {
+      rl.output.write('*');
+      return;
+    }
+    originalWrite.call(rl, stringToWrite);
+  };
+  rl.stdoutMuted = true;
+  const secret = await new Promise((resolve) => {
+    rl.question(promptText, (answer) => resolve(`${answer || ''}`.trim()));
+  });
+  rl.stdoutMuted = false;
+  rl.close();
+  process.stdout.write('\n');
+  return secret;
+}
+
 function extractGatewayTokenFromConfig(config) {
   const mode = `${config?.gateway?.auth?.mode || ''}`.trim().toLowerCase();
   if (mode === 'password') {
@@ -278,6 +351,11 @@ function maskToken(token) {
   return `${text.slice(0, 4)}...${text.slice(-2)}`;
 }
 
+function maskTunnelPasswordInCommand(commandText) {
+  if (!commandText) return '';
+  return commandText.replace(/(--passwd\s+)([^\s]+)/i, '$1***');
+}
+
 function parsePortOrDefault(raw, fallback) {
   const parsed = Number.parseInt(`${raw ?? ''}`, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
@@ -911,6 +989,135 @@ async function runDoctor(options) {
   }
 }
 
+function buildConnectArgsFromConfig(config) {
+  const args = [
+    'connect',
+    '--openclaw-url', `${config.openclawUrl}`,
+    '--chat-path', `${config.chatPath}`,
+    '--host', `${config.listenHost}`,
+    '--port', `${config.port}`,
+    '--lan-host', `${config.lanHost}`,
+    '--agent-id', `${config.agentId}`,
+    '--name', `${config.name}`,
+    '--token', `${config.token}`,
+    '--expires-minutes', `${Math.max(1, Math.ceil((config.expiresAt.getTime() - Date.now()) / 60000))}`,
+    '--upstream-timeout-ms', `${config.upstreamTimeoutMs}`,
+    '--chat-mode', `${config.chatMode}`,
+    '--session-key', `${config.sessionKey}`,
+  ];
+
+  if (config.upstreamToken) {
+    args.push('--upstream-token', `${config.upstreamToken}`);
+  }
+  if (config.lanOnly) {
+    args.push('--lan-only');
+  }
+  if (config.publicBaseUrl) {
+    args.push('--public-base-url', `${config.publicBaseUrl}`);
+  }
+  if (config.tunnel?.enabled) {
+    args.push('--tunnel');
+    args.push('--tunnel-client', `${config.tunnel.client}`);
+    if (config.tunnel.bin) args.push('--tunnel-bin', `${config.tunnel.bin}`);
+    if (config.tunnel.user) args.push('--tunnel-user', `${config.tunnel.user}`);
+    if (config.tunnel.host) args.push('--tunnel-host', `${config.tunnel.host}`);
+    if (config.tunnel.password) args.push('--tunnel-password', `${config.tunnel.password}`);
+    if (config.tunnel.serverPort) args.push('--tunnel-server-port', `${config.tunnel.serverPort}`);
+    if (config.tunnel.remotePort) args.push('--tunnel-remote-port', `${config.tunnel.remotePort}`);
+  }
+  return args;
+}
+
+async function startConnectorService(config) {
+  const existing = readServiceRecord();
+  if (existing?.pid && isPidRunning(existing.pid)) {
+    return {
+      ok: false,
+      message: `Connector service is already running (PID ${existing.pid}). Run service-stop first.`,
+    };
+  }
+
+  const { baseDir, outLogPath, errLogPath } = resolveServicePaths();
+  fs.mkdirSync(baseDir, { recursive: true });
+  const outFd = fs.openSync(outLogPath, 'a');
+  const errFd = fs.openSync(errLogPath, 'a');
+  const args = buildConnectArgsFromConfig(config);
+  const child = spawn(process.execPath, [CURRENT_CLI_PATH, ...args], {
+    detached: true,
+    windowsHide: true,
+    stdio: ['ignore', outFd, errFd],
+  });
+  child.unref();
+  fs.closeSync(outFd);
+  fs.closeSync(errFd);
+
+  writeServiceRecord({
+    pid: child.pid,
+    startedAt: new Date().toISOString(),
+    sessionKey: config.sessionKey,
+    baseUrl: config.baseUrl,
+    localBaseUrl: config.localBaseUrl,
+    outLogPath,
+    errLogPath,
+  });
+
+  return {
+    ok: true,
+    pid: child.pid,
+    outLogPath,
+    errLogPath,
+  };
+}
+
+async function runServiceStop() {
+  const record = readServiceRecord();
+  if (!record?.pid) {
+    console.log('[PASS] No background connector service record found.');
+    return;
+  }
+  const pid = Number.parseInt(`${record.pid || ''}`, 10);
+  if (!Number.isFinite(pid) || pid <= 0) {
+    deleteServiceRecord();
+    console.log('[WARN] Service PID record is invalid. Record removed.');
+    return;
+  }
+  if (!isPidRunning(pid)) {
+    deleteServiceRecord();
+    console.log(`[PASS] Connector service PID ${pid} is not running. Record removed.`);
+    return;
+  }
+  try {
+    process.kill(pid);
+    deleteServiceRecord();
+    console.log(`[PASS] Stopped connector service (PID ${pid}).`);
+  } catch (error) {
+    throw new Error(`Failed to stop connector service PID ${pid}: ${error?.message || error}`);
+  }
+}
+
+async function runServiceStatus() {
+  const record = readServiceRecord();
+  if (!record?.pid) {
+    console.log('[PASS] Connector service is not running (no record).');
+    return;
+  }
+  const running = isPidRunning(record.pid);
+  console.log('');
+  console.log('MateClaw Connector Service Status');
+  console.log('================================');
+  console.log(`PID       : ${record.pid}`);
+  console.log(`Running   : ${running ? 'yes' : 'no'}`);
+  console.log(`StartedAt : ${record.startedAt || '-'}`);
+  console.log(`Session   : ${record.sessionKey || '-'}`);
+  console.log(`Base URL  : ${record.baseUrl || '-'}`);
+  console.log(`Out Log   : ${record.outLogPath || '-'}`);
+  console.log(`Err Log   : ${record.errLogPath || '-'}`);
+  console.log('');
+  if (!running) {
+    console.log('[WARN] Service record exists but process is not running. Consider service-stop to clean record.');
+  }
+}
+
 async function runInstall(options) {
   const dryRun = optionEnabled(options, 'dry-run');
   const skipGatewayRestart = optionEnabled(options, 'skip-gateway-restart');
@@ -928,6 +1135,35 @@ async function runInstall(options) {
   printInstallFixSummary(fixResult, dryRun);
 
   const installOptions = { ...options };
+  const lanOnly = optionEnabled(installOptions, 'lan-only');
+  if (installOptions['chat-mode'] == null) {
+    installOptions['chat-mode'] = DEFAULT_CHAT_MODE;
+  }
+  if (installOptions['session-key'] == null) {
+    installOptions['session-key'] = DEFAULT_SESSION_KEY;
+  }
+  if (!lanOnly && installOptions.tunnel == null && DEFAULT_PRESET_TUNNEL_ENABLED) {
+    installOptions.tunnel = 'true';
+  }
+  if (installOptions['tunnel-client'] == null) {
+    installOptions['tunnel-client'] = DEFAULT_TUNNEL_CLIENT;
+  }
+  if (installOptions['tunnel-user'] == null) {
+    installOptions['tunnel-user'] = DEFAULT_PRESET_TUNNEL_USER;
+  }
+  if (installOptions['tunnel-host'] == null) {
+    installOptions['tunnel-host'] = DEFAULT_PRESET_TUNNEL_HOST;
+  }
+  if (installOptions['tunnel-password'] == null) {
+    installOptions['tunnel-password'] = DEFAULT_PRESET_TUNNEL_PASSWORD;
+  }
+  if (!lanOnly && installOptions['public-base-url'] == null) {
+    installOptions['public-base-url'] = DEFAULT_PRESET_PUBLIC_BASE_URL;
+  }
+  if (lanOnly) {
+    installOptions.tunnel = 'false';
+    delete installOptions['public-base-url'];
+  }
 
   const openclawUrl = stripTrailingSlash(
     installOptions['openclaw-url'] ||
@@ -1024,11 +1260,27 @@ async function runInstall(options) {
     return;
   }
 
-  const config = buildConfig(installOptions);
-  await startConnector(config);
+  const config = await buildConfig(installOptions);
+  const foreground = optionEnabled(installOptions, 'foreground');
+  if (foreground) {
+    console.log('[WARN] Running connector in foreground mode (--foreground). Keep this CMD open.');
+    await startConnector(config);
+    return;
+  }
+
+  const serviceStart = await startConnectorService(config);
+  if (!serviceStart.ok) {
+    throw new Error(serviceStart.message || 'Failed to start background connector service.');
+  }
+  console.log(`[PASS] Connector service started in background (PID ${serviceStart.pid}).`);
+  console.log('[PASS] You can now close this CMD window.');
+  console.log(`[PASS] Service logs: ${serviceStart.outLogPath}`);
+  console.log('[PASS] Stop service: npx -y mateclaw-openclaw-plugin service-stop');
+  console.log('[PASS] Service status: npx -y mateclaw-openclaw-plugin service-status');
+  printBanner(config);
 }
 
-function buildConfig(options) {
+async function buildConfig(options) {
   const openclawUrl = stripTrailingSlash(
     options['openclaw-url'] ||
         process.env.OPENCLAW_BASE_URL ||
@@ -1057,6 +1309,10 @@ function buildConfig(options) {
       process.env.MATECLAW_CONNECTOR_LAN_HOST ||
       lanCandidates[0]?.address ||
       '';
+  const lanOnly = optionEnabled(options, 'lan-only');
+  const publicBaseUrl = normalizePublicBaseUrl(
+    options['public-base-url'] || process.env.MATECLAW_PUBLIC_BASE_URL || '',
+  );
   const agentId =
       options['agent-id'] || process.env.MATECLAW_AGENT_ID || DEFAULT_AGENT_ID;
   const sessionKey = normalizeSessionKey(
@@ -1085,6 +1341,22 @@ function buildConfig(options) {
       process.env.OPENCLAW_UPSTREAM_TOKEN ||
       detectLocalDeviceAuthToken() ||
       detectLocalGatewayToken();
+  const tunnelEnabled = !lanOnly && optionEnabled(options, 'tunnel');
+  const tunnelClient = normalizeTunnelClient(
+    options['tunnel-client'] || process.env.MATECLAW_TUNNEL_CLIENT || '',
+  );
+  const tunnelBin = `${options['tunnel-bin'] || process.env.MATECLAW_TUNNEL_BIN || tunnelClient}`.trim();
+  const tunnelUser = `${options['tunnel-user'] || process.env.MATECLAW_TUNNEL_USER || ''}`.trim();
+  const tunnelHost = `${options['tunnel-host'] || process.env.MATECLAW_TUNNEL_HOST || ''}`.trim();
+  let tunnelPassword = `${options['tunnel-password'] || process.env.MATECLAW_TUNNEL_PASSWORD || ''}`.trim();
+  const tunnelServerPort = parsePortOrDefault(
+    options['tunnel-server-port'] || process.env.MATECLAW_TUNNEL_SERVER_PORT || `${DEFAULT_TUNNEL_SERVER_PORT}`,
+    DEFAULT_TUNNEL_SERVER_PORT,
+  );
+  const tunnelRemotePort = parsePortOrDefault(
+    options['tunnel-remote-port'] || process.env.MATECLAW_TUNNEL_REMOTE_PORT || `${DEFAULT_TUNNEL_REMOTE_PORT}`,
+    DEFAULT_TUNNEL_REMOTE_PORT,
+  );
 
   if (!Number.isFinite(port) || port <= 0) {
     throw new Error('Invalid port.');
@@ -1100,9 +1372,29 @@ function buildConfig(options) {
       'Unable to detect a LAN host automatically. Pass --lan-host or set MATECLAW_CONNECTOR_LAN_HOST.',
     );
   }
+  if (tunnelEnabled && (!tunnelUser || !tunnelHost)) {
+    throw new Error(
+      'Tunnel enabled but tunnel target is incomplete. Pass --tunnel-user and --tunnel-host.',
+    );
+  }
+  if (tunnelEnabled && tunnelClient !== 'builtin' && !isCommandAvailable(tunnelBin)) {
+    throw new Error(
+      `Tunnel client not found: ${tunnelBin}. Install it or set --tunnel-bin with a valid command.`,
+    );
+  }
+  if (tunnelEnabled && (tunnelClient === 'nssh' || tunnelClient === 'builtin') && !tunnelPassword) {
+    tunnelPassword = await readSecretFromPrompt('Tunnel password (hidden input): ');
+  }
+  if (tunnelEnabled && (tunnelClient === 'nssh' || tunnelClient === 'builtin') && !tunnelPassword) {
+    throw new Error(
+      `Tunnel client ${tunnelClient} requires --tunnel-password (or MATECLAW_TUNNEL_PASSWORD).`,
+    );
+  }
 
   const expiresAt = new Date(Date.now() + expiresMinutes * 60 * 1000);
-  const baseUrl = `http://${lanHost}:${port}`;
+  const localBaseUrl = `http://${lanHost}:${port}`;
+  const effectivePublicBaseUrl = tunnelEnabled ? publicBaseUrl : '';
+  const baseUrl = effectivePublicBaseUrl || localBaseUrl;
 
   return {
     openclawUrl,
@@ -1119,8 +1411,23 @@ function buildConfig(options) {
     upstreamTimeoutMs,
     upstreamToken,
     lanCandidates,
+    lanOnly,
+    localBaseUrl,
+    publicBaseUrl: effectivePublicBaseUrl,
     baseUrl,
     acceptedChatPaths,
+    tunnel: {
+      enabled: tunnelEnabled,
+      client: tunnelClient,
+      bin: tunnelBin,
+      user: tunnelUser,
+      host: tunnelHost,
+      password: tunnelPassword,
+      serverPort: tunnelServerPort,
+      remotePort: tunnelRemotePort,
+      localHost: DEFAULT_TUNNEL_LOCAL_HOST,
+      localPort: port,
+    },
     qrPayload: {
       type: PAYLOAD_TYPE,
       name,
@@ -1188,6 +1495,254 @@ function loadLocalDeviceIdentity() {
   }
 }
 
+function buildTunnelLaunchPlan(config) {
+  const tunnel = config.tunnel;
+  if (!tunnel?.enabled) return null;
+
+  const routeSpec = `${tunnel.remotePort}:${tunnel.localHost}:${tunnel.localPort}`;
+  const destination = `${tunnel.user}@${tunnel.host}`;
+  const command = tunnel.bin || tunnel.client;
+  const args = ['-R', routeSpec, destination];
+
+  if (tunnel.serverPort && tunnel.serverPort !== DEFAULT_TUNNEL_SERVER_PORT) {
+    args.push('-p', `${tunnel.serverPort}`);
+  }
+
+  if (tunnel.client === 'nssh') {
+    args.push('--passwd', tunnel.password);
+  }
+
+  return {
+    command,
+    args,
+    routeSpec,
+    destination,
+  };
+}
+
+function resolveServicePaths() {
+  const baseDir = path.join(os.homedir(), '.openclaw', 'mateclaw-openclaw-plugin');
+  return {
+    baseDir,
+    pidFilePath: path.join(baseDir, 'connector-service.json'),
+    outLogPath: path.join(baseDir, 'connector-service.out.log'),
+    errLogPath: path.join(baseDir, 'connector-service.err.log'),
+  };
+}
+
+function readServiceRecord() {
+  const { pidFilePath } = resolveServicePaths();
+  const snapshot = readJsonFileSafe(pidFilePath);
+  if (!snapshot.exists || !snapshot.valid || !snapshot.value || typeof snapshot.value !== 'object') {
+    return null;
+  }
+  return snapshot.value;
+}
+
+function isPidRunning(pid) {
+  const numericPid = Number.parseInt(`${pid || ''}`, 10);
+  if (!Number.isFinite(numericPid) || numericPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writeServiceRecord(record) {
+  const { baseDir, pidFilePath } = resolveServicePaths();
+  fs.mkdirSync(baseDir, { recursive: true });
+  writeJsonFile(pidFilePath, record);
+}
+
+function deleteServiceRecord() {
+  const { pidFilePath } = resolveServicePaths();
+  if (fs.existsSync(pidFilePath)) {
+    fs.unlinkSync(pidFilePath);
+  }
+}
+
+function launchExternalTunnel(plan) {
+  const commandText = `${plan.command} ${plan.args.join(' ')}`;
+  try {
+    const child = spawn(plan.command, plan.args, {
+      shell: process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    child.stdout?.on('data', (chunk) => {
+      const text = `${chunk || ''}`.trim();
+      if (text) {
+        console.log(`[tunnel] ${text}`);
+      }
+    });
+    child.stderr?.on('data', (chunk) => {
+      const text = `${chunk || ''}`.trim();
+      if (text) {
+        console.log(`[tunnel][stderr] ${text}`);
+      }
+    });
+    child.on('exit', (code, signal) => {
+      const reason = signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`;
+      console.log(`[WARN] Tunnel process exited (${reason}).`);
+    });
+
+    return {
+      enabled: true,
+      started: true,
+      child,
+      stop: null,
+      error: '',
+      commandText,
+      destination: plan.destination,
+      routeSpec: plan.routeSpec,
+    };
+  } catch (error) {
+    return {
+      enabled: true,
+      started: false,
+      child: null,
+      stop: null,
+      error: `${error?.message || error}`,
+      commandText,
+      destination: plan.destination,
+      routeSpec: plan.routeSpec,
+    };
+  }
+}
+
+async function launchBuiltinTunnel(config, plan) {
+  const tunnel = config.tunnel;
+  const commandText = `builtin-ssh -R ${plan.routeSpec} ${plan.destination}${
+    tunnel.serverPort !== DEFAULT_TUNNEL_SERVER_PORT ? ` -p ${tunnel.serverPort}` : ''
+  }`;
+
+  return await new Promise((resolve) => {
+    const conn = new SshClient();
+    let settled = false;
+
+    const settle = (runtime) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(runtime);
+    };
+
+    const fail = (error) => {
+      const detail = `${error?.message || error || 'unknown error'}`;
+      try {
+        conn.end();
+      } catch {}
+      settle({
+        enabled: true,
+        started: false,
+        child: null,
+        stop: null,
+        error: detail,
+        commandText,
+        destination: plan.destination,
+        routeSpec: plan.routeSpec,
+      });
+    };
+
+    const timer = setTimeout(() => {
+      fail(new Error('builtin tunnel connection timeout'));
+    }, 12000);
+
+    conn.on('ready', () => {
+      conn.forwardIn('0.0.0.0', tunnel.remotePort, (error) => {
+        if (error) {
+          fail(error);
+          return;
+        }
+
+        settle({
+          enabled: true,
+          started: true,
+          child: null,
+          stop: () => {
+            try {
+              conn.end();
+            } catch {}
+          },
+          error: '',
+          commandText,
+          destination: plan.destination,
+          routeSpec: plan.routeSpec,
+        });
+      });
+    });
+
+    conn.on('tcp connection', (_details, accept) => {
+      const remoteStream = accept();
+      const localSocket = net.connect(tunnel.localPort, tunnel.localHost);
+
+      localSocket.on('error', (error) => {
+        console.log(`[WARN] Tunnel local socket error: ${error?.message || error}`);
+        try {
+          remoteStream.destroy(error);
+        } catch {}
+      });
+      remoteStream.on('error', (error) => {
+        console.log(`[WARN] Tunnel remote stream error: ${error?.message || error}`);
+        try {
+          localSocket.destroy(error);
+        } catch {}
+      });
+
+      remoteStream.pipe(localSocket);
+      localSocket.pipe(remoteStream);
+    });
+
+    conn.on('error', (error) => {
+      if (!settled) {
+        fail(error);
+        return;
+      }
+      console.log(`[WARN] Tunnel runtime error: ${error?.message || error}`);
+    });
+
+    conn.on('close', () => {
+      if (settled) {
+        console.log('[WARN] Tunnel process exited (builtin ssh closed).');
+      }
+    });
+
+    conn.connect({
+      host: tunnel.host,
+      port: tunnel.serverPort,
+      username: tunnel.user,
+      password: tunnel.password,
+      readyTimeout: 12000,
+      keepaliveInterval: 15000,
+      keepaliveCountMax: 4,
+    });
+  });
+}
+
+async function launchTunnel(config) {
+  const plan = buildTunnelLaunchPlan(config);
+  if (!plan) {
+    return {
+      enabled: false,
+      started: false,
+      child: null,
+      stop: null,
+      error: '',
+      commandText: '',
+    };
+  }
+
+  if (config.tunnel.client === 'builtin') {
+    return await launchBuiltinTunnel(config, plan);
+  }
+
+  return launchExternalTunnel(plan);
+}
+
 async function startConnector(config) {
   const server = http.createServer((req, res) => {
     handleRequest(req, res, config).catch((error) => {
@@ -1203,11 +1758,22 @@ async function startConnector(config) {
     server.listen(config.port, config.listenHost, resolve);
   });
 
+  const tunnelRuntime = await launchTunnel(config);
+  config.tunnelRuntime = tunnelRuntime;
+
   printBanner(config);
 
   const shutdown = () => {
-    console.log('\nShutting down Local OpenClaw Demo Connector...');
-    server.close(() => process.exit(0));
+    console.log('\nShutting down MateClaw OpenClaw Connector...');
+    const done = () => server.close(() => process.exit(0));
+    if (typeof tunnelRuntime?.stop === 'function') {
+      console.log('Stopping tunnel process...');
+      tunnelRuntime.stop();
+    } else if (tunnelRuntime?.child && !tunnelRuntime.child.killed) {
+      console.log('Stopping tunnel process...');
+      tunnelRuntime.child.kill();
+    }
+    done();
   };
 
   process.on('SIGINT', shutdown);
@@ -1227,7 +1793,7 @@ async function handleRequest(req, res, config) {
   if (requestUrl.pathname === '/health' && req.method === 'GET') {
     sendJson(res, 200, {
       ok: true,
-      mode: 'mateclaw_local_openclaw_demo',
+      mode: PAYLOAD_TYPE,
       chatMode: config.chatMode,
       sessionId: config.sessionKey,
       upstream: config.openclawUrl,
@@ -2058,6 +2624,30 @@ function stripTrailingSlash(value) {
   return value.replace(/\/+$/, '');
 }
 
+function normalizePublicBaseUrl(value) {
+  const raw = `${value || ''}`.trim();
+  if (!raw) return '';
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  try {
+    const parsed = new URL(withScheme);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error('Public base URL must start with http:// or https://');
+    }
+    return stripTrailingSlash(parsed.toString());
+  } catch {
+    throw new Error(`Invalid public-base-url: ${value}`);
+  }
+}
+
+function normalizeTunnelClient(value) {
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  if (!normalized) return DEFAULT_TUNNEL_CLIENT;
+  if (normalized === 'builtin' || normalized === 'ssh' || normalized === 'nssh') {
+    return normalized;
+  }
+  throw new Error(`Invalid tunnel-client: ${value}. Use builtin, ssh or nssh.`);
+}
+
 function normalizePath(value) {
   if (!value) {
     return DEFAULT_CHAT_PATH;
@@ -2235,8 +2825,9 @@ function isSpecialUseIpv4(address) {
 }
 
 function printBanner(config) {
+  const tunnelRuntime = config.tunnelRuntime || {};
   console.log('');
-  console.log('MateClaw Local OpenClaw Demo Connector');
+  console.log('MateClaw OpenClaw Connector');
   console.log('======================================');
   console.log(`Upstream OpenClaw : ${config.openclawUrl}`);
   console.log(`Chat Mode         : ${config.chatMode}`);
@@ -2244,9 +2835,10 @@ function printBanner(config) {
   console.log(`Chat Path         : ${config.chatPath}`);
   console.log(`Accepted Paths    : ${config.acceptedChatPaths.join(', ')}`);
   console.log(`Desktop Bind Host : ${config.listenHost}:${config.port}`);
+  console.log(`Local Access URL  : ${config.localBaseUrl}`);
   console.log(`Mobile Access URL : ${config.baseUrl}`);
   console.log(`Agent ID          : ${config.agentId}`);
-  console.log(`Token             : ${config.token}`);
+  console.log(`Token             : ${maskToken(config.token)}`);
   console.log(`Expires At        : ${config.expiresAt.toISOString()}`);
   console.log(`Upstream Timeout  : ${config.upstreamTimeoutMs}ms`);
   console.log(
@@ -2260,13 +2852,36 @@ function printBanner(config) {
       console.log(`  - ${item.address} (${item.iface}, score=${item.score})`);
     }
   }
+  if (config.tunnel?.enabled) {
+    console.log('Tunnel            : enabled');
+    console.log(`Tunnel Client     : ${config.tunnel.client}`);
+    if (tunnelRuntime.started) {
+      console.log(
+        `Tunnel Route      : ${config.tunnel.remotePort} -> ${config.tunnel.localHost}:${config.tunnel.localPort} (${config.tunnel.user}@${config.tunnel.host})`,
+      );
+      console.log(`Tunnel Command    : ${maskTunnelPasswordInCommand(tunnelRuntime.commandText)}`);
+    } else {
+      console.log(`Tunnel Status     : failed to start (${tunnelRuntime.error || 'unknown error'})`);
+      if (tunnelRuntime.commandText) {
+        console.log(`Tunnel Command    : ${maskTunnelPasswordInCommand(tunnelRuntime.commandText)}`);
+      }
+    }
+    if (!config.publicBaseUrl) {
+      console.log('[WARN] Tunnel is enabled but --public-base-url is missing. QR still points to LAN URL.');
+    }
+  } else if (config.lanOnly) {
+    console.log('Tunnel            : disabled (LAN-only mode)');
+  }
   console.log('');
-  console.log('FoloToy-style bind flow: install once -> scan the QR shown here -> chat.');
+  console.log('One-command bind flow: install once -> scan the QR shown here -> chat.');
   console.log('If binding fails, pin the LAN IP manually:');
   console.log(
     `  node ./src/cli.mjs install --lan-host ${config.lanHost || '<your-lan-ip>'} --port ${config.port}`,
   );
-  console.log(`Quick health URL: ${config.baseUrl}/health`);
+  console.log(`Quick health URL (local): ${config.localBaseUrl}/health`);
+  if (config.publicBaseUrl) {
+    console.log(`Public bind URL: ${config.publicBaseUrl}`);
+  }
   console.log('');
   console.log('Scan this QR code in the MateClaw app (this is the OpenClaw-side bind QR):');
   console.log('');