@wangzn04/openclaw-gwcheck 2026.3.3

package/index.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { runGatewayConfigCheck } from "./index.js";
+
+describe("gwcheck plugin", () => {
+  it("reports error when gateway.mode is missing", () => {
+    const report = runGatewayConfigCheck({});
+    expect(report.ok).toBe(false);
+    expect(report.findings.some((finding) => finding.code === "gateway_mode_missing")).toBe(true);
+  });
+
+  it("passes for local mode with token auth configured", () => {
+    const report = runGatewayConfigCheck({
+      gateway: {
+        mode: "local",
+        auth: {
+          mode: "token",
+          token: "test-token",
+        },
+      },
+    });
+
+    expect(report.ok).toBe(true);
+    expect(report.findings).toHaveLength(0);
+  });
+
+  it("flags insecure remote ws url", () => {
+    const report = runGatewayConfigCheck({
+      gateway: {
+        mode: "remote",
+        remote: {
+          url: "ws://example.com:18789",
+        },
+      },
+    });
+
+    expect(report.ok).toBe(false);
+    expect(report.findings.some((finding) => finding.code === "gateway_remote_url_insecure_ws")).toBe(
+      true,
+    );
+  });
+});

package/index.ts

@@ -0,0 +1,246 @@
+import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+
+type GatewayCheckLevel = "error" | "warning";
+
+type GatewayCheckFinding = {
+  level: GatewayCheckLevel;
+  code: string;
+  message: string;
+  fix?: string;
+};
+
+export type GatewayCheckReport = {
+  ok: boolean;
+  checkedAt: string;
+  findings: GatewayCheckFinding[];
+};
+
+function hasSecretLikeValue(value: unknown): boolean {
+  if (typeof value === "string") {
+    return value.trim().length > 0;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  return Object.keys(value as Record<string, unknown>).length > 0;
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const host = hostname.trim().toLowerCase();
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+function checkGatewayConfig(cfg: OpenClawConfig): GatewayCheckFinding[] {
+  const findings: GatewayCheckFinding[] = [];
+  const gateway = cfg.gateway ?? {};
+  const mode = gateway.mode;
+
+  if (mode !== "local" && mode !== "remote") {
+    findings.push({
+      level: "error",
+      code: "gateway_mode_missing",
+      message: "gateway.mode must be set to \"local\" or \"remote\".",
+      fix: "Run: openclaw config set gateway.mode local",
+    });
+    return findings;
+  }
+
+  const authMode = gateway.auth?.mode;
+  const authTokenConfigured = hasSecretLikeValue(gateway.auth?.token);
+  const authPasswordConfigured = hasSecretLikeValue(gateway.auth?.password);
+
+  if (!authMode && authTokenConfigured && authPasswordConfigured) {
+    findings.push({
+      level: "error",
+      code: "gateway_auth_mode_ambiguous",
+      message:
+        "gateway.auth.token and gateway.auth.password are both configured while gateway.auth.mode is unset.",
+      fix: "Run: openclaw config set gateway.auth.mode token",
+    });
+  }
+
+  if (mode === "local") {
+    if (authMode === "token" && !authTokenConfigured) {
+      findings.push({
+        level: "error",
+        code: "gateway_auth_token_missing",
+        message: "gateway.auth.mode is token but gateway.auth.token is missing.",
+        fix: "Run: openclaw config set gateway.auth.token \"<token>\"",
+      });
+    }
+
+    if (authMode === "password" && !authPasswordConfigured) {
+      findings.push({
+        level: "error",
+        code: "gateway_auth_password_missing",
+        message: "gateway.auth.mode is password but gateway.auth.password is missing.",
+        fix: "Run: openclaw config set gateway.auth.password \"<password>\"",
+      });
+    }
+
+    if (authMode === "trusted-proxy" && !gateway.auth?.trustedProxy?.userHeader?.trim()) {
+      findings.push({
+        level: "error",
+        code: "gateway_auth_trusted_proxy_missing_user_header",
+        message:
+          "gateway.auth.mode is trusted-proxy but gateway.auth.trustedProxy.userHeader is missing.",
+        fix: "Set gateway.auth.trustedProxy.userHeader to the proxy identity header.",
+      });
+    }
+
+    if (typeof gateway.remote?.url === "string" && gateway.remote.url.trim()) {
+      findings.push({
+        level: "warning",
+        code: "gateway_remote_url_ignored_in_local_mode",
+        message: "gateway.remote.url is set but gateway.mode is local; remote URL will be ignored.",
+      });
+    }
+
+    return findings;
+  }
+
+  const remoteUrlRaw = gateway.remote?.url;
+  const remoteUrl = typeof remoteUrlRaw === "string" ? remoteUrlRaw.trim() : "";
+  if (!remoteUrl) {
+    findings.push({
+      level: "error",
+      code: "gateway_remote_url_missing",
+      message: "gateway.mode is remote but gateway.remote.url is missing.",
+      fix: "Run: openclaw config set gateway.remote.url \"wss://host:port\"",
+    });
+    return findings;
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(remoteUrl);
+  } catch {
+    findings.push({
+      level: "error",
+      code: "gateway_remote_url_invalid",
+      message: `gateway.remote.url is not a valid URL: ${remoteUrl}`,
+      fix: "Use ws:// or wss:// URL format.",
+    });
+    return findings;
+  }
+
+  if (parsedUrl.protocol !== "ws:" && parsedUrl.protocol !== "wss:") {
+    findings.push({
+      level: "error",
+      code: "gateway_remote_url_protocol_invalid",
+      message: `gateway.remote.url must start with ws:// or wss:// (got ${parsedUrl.protocol}).`,
+      fix: "Use wss://host:port for remote gateway access.",
+    });
+  }
+
+  if (parsedUrl.protocol === "ws:" && !isLoopbackHost(parsedUrl.hostname)) {
+    findings.push({
+      level: "error",
+      code: "gateway_remote_url_insecure_ws",
+      message:
+        "gateway.remote.url uses insecure ws:// for a non-loopback host; this can expose credentials and traffic.",
+      fix: "Use wss://, or keep gateway on loopback and tunnel via SSH/Tailscale.",
+    });
+  }
+
+  if (gateway.remote?.transport === "ssh" && !gateway.remote?.sshTarget?.trim()) {
+    findings.push({
+      level: "warning",
+      code: "gateway_remote_ssh_target_missing",
+      message: "gateway.remote.transport is ssh but gateway.remote.sshTarget is missing.",
+      fix: "Run: openclaw config set gateway.remote.sshTarget \"user@host\"",
+    });
+  }
+
+  return findings;
+}
+
+export function runGatewayConfigCheck(cfg: OpenClawConfig): GatewayCheckReport {
+  const findings = checkGatewayConfig(cfg);
+  const hasErrors = findings.some((finding) => finding.level === "error");
+  return {
+    ok: !hasErrors,
+    checkedAt: new Date().toISOString(),
+    findings,
+  };
+}
+
+function printGatewayCheckReport(report: GatewayCheckReport): void {
+  if (report.findings.length === 0) {
+    console.log("Gateway config check passed.");
+    return;
+  }
+
+  const errors = report.findings.filter((finding) => finding.level === "error");
+  const warnings = report.findings.filter((finding) => finding.level === "warning");
+
+  if (errors.length > 0) {
+    console.log(`Gateway config check failed with ${errors.length} error(s).`);
+    for (const finding of errors) {
+      console.log(`- [${finding.code}] ${finding.message}`);
+      if (finding.fix) {
+        console.log(`  Fix: ${finding.fix}`);
+      }
+    }
+  }
+
+  if (warnings.length > 0) {
+    console.log(`Gateway config warnings: ${warnings.length}`);
+    for (const finding of warnings) {
+      console.log(`- [${finding.code}] ${finding.message}`);
+      if (finding.fix) {
+        console.log(`  Hint: ${finding.fix}`);
+      }
+    }
+  }
+}
+
+const gwcheckPlugin = {
+  id: "gwcheck",
+  name: "Gateway Config Check",
+  description: "Adds a top-level gwcheck command for gateway config checks",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    api.registerCli(
+      ({ program }) => {
+        program
+          .command("gwcheck")
+          .description("Check gateway config semantics")
+          .option("--json", "Output report as JSON", false)
+          .action((opts: { json?: boolean }) => {
+            let cfg: OpenClawConfig;
+            try {
+              cfg = api.runtime.config.loadConfig();
+            } catch (err) {
+              const error = {
+                ok: false,
+                error: `Failed to load config: ${String(err)}`,
+              };
+              if (opts.json) {
+                console.log(JSON.stringify(error, null, 2));
+              } else {
+                console.error(error.error);
+              }
+              process.exitCode = 1;
+              return;
+            }
+
+            const report = runGatewayConfigCheck(cfg);
+            if (opts.json) {
+              console.log(JSON.stringify(report, null, 2));
+            } else {
+              printGatewayCheckReport(report);
+            }
+
+            if (!report.ok) {
+              process.exitCode = 1;
+            }
+          });
+      },
+      { commands: ["gwcheck"] },
+    );
+  },
+};
+
+export default gwcheckPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "gwcheck",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@wangzn04/openclaw-gwcheck",
+  "version": "2026.3.3",
+  "private": false,
+  "description": "OpenClaw gateway config check plugin",
+  "type": "module",
+  "peerDependencies": {
+    "openclaw": ">=2026.3.2"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}