@openbrt/weclawbotctl 0.1.6 → 0.1.8

package/README.md

@@ -67,6 +67,11 @@ skill, `weclawbot_status`, `weclawbot_validate_screen_document`,
 polls `weclawbot.link`; no public HTTP endpoint, port forwarding, or WeChat
 credential is required on the OpenClaw host.
 
+OpenClaw plugin tools require OpenClaw `2026.6.9` or newer because the plugin
+declares `contracts.tools`. Older OpenClaw builds can still run
+`weclawbotctl` as a shell command, but the agent tool injection will not be
+reliable.
+
 ## Install from npm
 
 ```bash
@@ -86,9 +91,35 @@ Agent.
 To install the OpenClaw plugin itself from npm after the package is published:
 
 ```bash
-openclaw plugins install @openbrt/weclawbotctl --pin
+weclawbotctl openclaw install
+weclawbotctl openclaw doctor
+```
+
+This wraps:
+
+```bash
+openclaw plugins install @openbrt/weclawbotctl --pin --force
+openclaw plugins enable weclawbot
 ```
 
+Restart the OpenClaw gateway or app after installation so it reloads plugin
+tools. The doctor checks the OpenClaw version, plugin installation, plugin
+diagnostics, and local gateway reachability. If a local WSS gateway uses a
+self-signed certificate, the doctor will suggest `NODE_EXTRA_CA_CERTS`. If the
+certificate lacks `localhost` or `127.0.0.1` SANs, fix the gateway certificate
+or use a certificate trusted by Node. The package does not rewrite other
+users' OpenClaw gateway certificates automatically.
+
+If OpenClaw is installed outside `PATH`, pass it explicitly:
+
+```bash
+weclawbotctl openclaw doctor --bin /path/to/openclaw
+```
+
+When `weclawbotctl` is installed globally, it also checks the same npm global
+`bin` directory for `openclaw`, which helps non-interactive SSH and systemd
+environments where shell startup files are not loaded.
+
 To install the OpenClaw plugin from a local checkout during development:
 
 ```bash

package/bin/weclawbotctl.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import crypto from "node:crypto";
+import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -12,9 +13,11 @@ import { normalizeCredentials, publishControl, testConnection } from "../lib/mqt
 
 const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
+const DEFAULT_OPENCLAW_PLUGIN_SPEC = "@openbrt/weclawbotctl";
+const MIN_OPENCLAW_VERSION = "2026.6.9";
 
 const [command, ...args] = process.argv.slice(2);
-const commands = new Set(["bind", "status", "doctor", "export", "unbind", "thinking", "idle", "screen"]);
+const commands = new Set(["bind", "status", "doctor", "export", "unbind", "thinking", "idle", "screen", "openclaw"]);
 if (!commands.has(command)) {
   usage();
   process.exit(64);
@@ -27,6 +30,7 @@ try {
   else if (command === "export") await commandExport(args);
   else if (command === "unbind") await commandUnbind(args);
   else if (command === "screen") await commandScreen(args);
+  else if (command === "openclaw") await commandOpenClaw(args);
   else await commandActivity(command, args);
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));
@@ -250,6 +254,91 @@ async function commandActivity(state, values) {
   console.log(JSON.stringify({ ok: true, state: activity.state, correlation_id: correlationId }));
 }
 
+async function commandOpenClaw(values) {
+  const first = String(values[0] || "");
+  const subcommand = first && !first.startsWith("--") ? first : "doctor";
+  const rest = first && !first.startsWith("--") ? values.slice(1) : values;
+  if (subcommand === "install") {
+    await commandOpenClawInstall(rest);
+  } else if (subcommand === "doctor") {
+    await commandOpenClawDoctor(rest);
+  } else {
+    throw new Error("Usage: weclawbotctl openclaw install|doctor");
+  }
+}
+
+async function commandOpenClawInstall(values) {
+  const options = parseOptions(values, {
+    bin: process.env.OPENCLAW_BIN || "",
+    spec: DEFAULT_OPENCLAW_PLUGIN_SPEC,
+    force: true,
+    doctor: true,
+  });
+  const openclaw = await resolveOpenClawBin(options.bin);
+  const spec = String(options.spec || DEFAULT_OPENCLAW_PLUGIN_SPEC);
+  const version = await runCaptured(openclaw, ["--version"], { timeoutMs: 10_000 });
+  const versionCheck = openClawVersionCheck(version.stdout);
+  if (version.code !== 0) throw new Error(`OpenClaw CLI not found. Install OpenClaw or set OPENCLAW_BIN=/path/to/openclaw.`);
+  if (!versionCheck.ok) throw new Error(`${versionCheck.detail}. ${versionCheck.hint}`);
+  const installArgs = ["plugins", "install", spec, "--pin"];
+  if (options.force) installArgs.push("--force");
+  await runRequired(openclaw, installArgs);
+  await runRequired(openclaw, ["plugins", "enable", "weclawbot"]);
+  console.log("OpenClaw plugin installed and enabled. Restart the OpenClaw gateway or app so it reloads plugins.");
+  if (options.doctor) {
+    await commandOpenClawDoctor(["--bin", openclaw, "--gateway=false"]);
+  }
+}
+
+async function commandOpenClawDoctor(values) {
+  const options = parseOptions(values, {
+    bin: process.env.OPENCLAW_BIN || "",
+    json: false,
+    gateway: true,
+    timeout: 20,
+  });
+  const openclaw = await resolveOpenClawBin(options.bin);
+  const timeoutMs = Math.max(1, Number(options.timeout) || 20) * 1000;
+  const checks = [];
+
+  const version = await runCaptured(openclaw, ["--version"], { timeoutMs });
+  pushProcessCheck(checks, "openclaw_bin", version, "OpenClaw CLI found");
+  if (version.code === 0) checks.push(openClawVersionCheck(version.stdout));
+
+  const inspect = await runCaptured(openclaw, ["plugins", "inspect", "weclawbot"], { timeoutMs });
+  checks.push({
+    name: "openclaw_plugin",
+    ok: inspect.code === 0,
+    detail: inspect.code === 0 ? summarizeOpenClawPlugin(inspect.stdout) : compactText(inspect.stderr || inspect.stdout || "not installed"),
+    hint: inspect.code === 0 ? "" : `Run: weclawbotctl openclaw install`,
+  });
+
+  const pluginDoctor = await runCaptured(openclaw, ["plugins", "doctor"], { timeoutMs });
+  const doctorText = `${pluginDoctor.stdout}\n${pluginDoctor.stderr}`;
+  const weclawbotIssue = /(^|\n)\s*-\s*weclawbot:|weclawbot.*contracts\.tools|weclawbot.*plugin/i.test(doctorText);
+  checks.push({
+    name: "openclaw_plugin_doctor",
+    ok: pluginDoctor.code === 0 && !weclawbotIssue,
+    detail: pluginDoctor.code === 0 && !weclawbotIssue
+      ? "no WeClawBot plugin issues detected"
+      : compactText(doctorText || `exit ${pluginDoctor.code}`),
+    hint: weclawbotIssue ? "Upgrade and reinstall: weclawbotctl openclaw install" : "",
+  });
+
+  if (options.gateway) {
+    const gatewayEnv = { ...process.env };
+    const defaultCert = path.join(os.homedir(), ".openclaw", "gateway", "tls", "gateway-cert.pem");
+    if (!gatewayEnv.NODE_EXTRA_CA_CERTS && await fileExists(defaultCert)) {
+      gatewayEnv.NODE_EXTRA_CA_CERTS = defaultCert;
+    }
+    const status = await runCaptured(openclaw, ["status", "--json"], { env: gatewayEnv, timeoutMs });
+    checks.push(gatewayStatusCheck(status, gatewayEnv.NODE_EXTRA_CA_CERTS || ""));
+  }
+
+  printOpenClawDoctor(checks, options.json);
+  if (checks.some((check) => !check.ok)) process.exitCode = 1;
+}
+
 function parseOptions(values, defaults = {}) {
   const options = { ...defaults, _: [] };
   for (let index = 0; index < values.length; index += 1) {
@@ -340,6 +429,180 @@ function printDoctor(checks, json) {
   }
 }
 
+function printOpenClawDoctor(checks, json) {
+  if (json) {
+    console.log(JSON.stringify({ ok: checks.every((check) => check.ok), checks }, null, 2));
+    return;
+  }
+  for (const check of checks) {
+    console.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}`);
+    if (!check.ok && check.hint) console.log(`hint ${check.name}: ${check.hint}`);
+  }
+}
+
+async function runRequired(file, args) {
+  const result = await runProcess(file, args, { stdio: "inherit" });
+  if (result.code !== 0) {
+    throw new Error(`${file} ${args.join(" ")} failed with exit ${result.code}`);
+  }
+}
+
+async function runCaptured(file, args, options = {}) {
+  return runProcess(file, args, { ...options, stdio: "pipe" });
+}
+
+function runProcess(file, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(file, args, {
+      env: options.env || process.env,
+      stdio: options.stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timeoutMs = Number(options.timeoutMs || 0);
+    const timeout = timeoutMs > 0 ? setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs) : null;
+    if (child.stdout) child.stdout.on("data", (chunk) => { stdout += chunk; });
+    if (child.stderr) child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => {
+      if (timeout) clearTimeout(timeout);
+      resolve({ code: 127, stdout, stderr: error.message, timedOut });
+    });
+    child.on("close", (code) => {
+      if (timeout) clearTimeout(timeout);
+      resolve({ code: timedOut ? 124 : (code ?? 1), stdout, stderr, timedOut });
+    });
+  });
+}
+
+function pushProcessCheck(checks, name, result, okDetail) {
+  checks.push({
+    name,
+    ok: result.code === 0,
+    detail: result.code === 0 ? compactText(result.stdout || okDetail) : compactText(result.stderr || result.stdout || `exit ${result.code}`),
+    hint: result.code === 127 ? "Install OpenClaw or set OPENCLAW_BIN=/path/to/openclaw." : "",
+  });
+}
+
+function openClawVersionCheck(output) {
+  const version = parseOpenClawVersion(output);
+  if (!version) {
+    return {
+      name: "openclaw_version",
+      ok: true,
+      detail: compactText(output || "version unknown"),
+      hint: "",
+    };
+  }
+  const ok = compareDottedVersion(version, MIN_OPENCLAW_VERSION) >= 0;
+  return {
+    name: "openclaw_version",
+    ok,
+    detail: `OpenClaw ${version} (requires >= ${MIN_OPENCLAW_VERSION})`,
+    hint: ok ? "" : "Upgrade OpenClaw before installing the WeClawBot plugin tools.",
+  };
+}
+
+function parseOpenClawVersion(output) {
+  const match = String(output || "").match(/OpenClaw\s+([0-9]+(?:\.[0-9]+){1,3})/u);
+  return match ? match[1] : "";
+}
+
+function compareDottedVersion(left, right) {
+  const a = String(left).split(".").map((part) => Number(part) || 0);
+  const b = String(right).split(".").map((part) => Number(part) || 0);
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (a[index] || 0) - (b[index] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+function summarizeOpenClawPlugin(output) {
+  const lines = String(output || "").split(/\r?\n/u);
+  const wanted = [];
+  for (const line of lines) {
+    if (/^(Status|Version|Source|Install path|Spec):/u.test(line.trim())) wanted.push(line.trim());
+  }
+  return wanted.length ? wanted.join("; ") : "installed";
+}
+
+function gatewayStatusCheck(result, extraCaCerts) {
+  const text = `${result.stdout}\n${result.stderr}`;
+  if (result.code !== 0) {
+    return {
+      name: "openclaw_gateway_status",
+      ok: false,
+      detail: compactText(text || `exit ${result.code}`),
+      hint: tlsHint(text, extraCaCerts),
+    };
+  }
+  try {
+    const status = JSON.parse(result.stdout);
+    const gateway = status.gateway || {};
+    const ok = gateway.reachable === true;
+    return {
+      name: "openclaw_gateway_status",
+      ok,
+      detail: ok ? `reachable ${gateway.url || ""}`.trim() : compactText(gateway.error || "gateway not reachable"),
+      hint: ok ? "" : tlsHint(gateway.error || text, extraCaCerts),
+    };
+  } catch {
+    return {
+      name: "openclaw_gateway_status",
+      ok: false,
+      detail: compactText(text || "status JSON parse failed"),
+      hint: tlsHint(text, extraCaCerts),
+    };
+  }
+}
+
+function tlsHint(text, extraCaCerts) {
+  const value = String(text || "");
+  if (/self-signed certificate/i.test(value)) {
+    return extraCaCerts
+      ? `Retry with NODE_EXTRA_CA_CERTS=${extraCaCerts}, or use a gateway certificate trusted by Node.`
+      : "If your OpenClaw gateway uses a self-signed cert, set NODE_EXTRA_CA_CERTS to its CA/cert path.";
+  }
+  if (/ALTNAME|Hostname\/IP does not match certificate/i.test(value)) {
+    return "Regenerate the OpenClaw gateway certificate with SANs for localhost and 127.0.0.1, or configure OpenClaw to use a valid certificate.";
+  }
+  return "";
+}
+
+async function fileExists(file) {
+  try {
+    await fs.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveOpenClawBin(value) {
+  if (value) return String(value);
+  const scriptDir = path.dirname(process.argv[1] || "");
+  const candidates = [
+    scriptDir ? path.join(scriptDir, "openclaw") : "",
+    path.join(os.homedir(), ".npm-global", "bin", "openclaw"),
+    path.join(os.homedir(), ".local", "bin", "openclaw"),
+    "/usr/local/bin/openclaw",
+    "/opt/homebrew/bin/openclaw",
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) return candidate;
+  }
+  return "openclaw";
+}
+
+function compactText(value) {
+  return String(value || "").replace(/\s+/gu, " ").trim().slice(0, 500);
+}
+
 function shellValue(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
@@ -357,5 +620,7 @@ function usage() {
   weclawbotctl unbind --yes
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
-  weclawbotctl screen <document.json> [--force]`);
+  weclawbotctl screen <document.json> [--force]
+  weclawbotctl openclaw install [--spec @openbrt/weclawbotctl] [--bin /path/to/openclaw] [--force=false]
+  weclawbotctl openclaw doctor [--gateway=false] [--bin /path/to/openclaw] [--json]`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbrt/weclawbotctl",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "WeClawBot pairing and screen-control CLI for local AI agents.",
   "type": "module",
   "license": "MIT",