nextclaw 0.5.2 → 0.5.4

package/dist/cli/index.js

@@ -63,6 +63,7 @@ import {
   writeFileSync as writeFileSync2
 } from "fs";
 import { dirname, join as join3, resolve as resolve4 } from "path";
+import { createServer as createNetServer } from "net";
 import { spawn as spawn2, spawnSync as spawnSync3 } from "child_process";
 import { createInterface } from "readline";
 import { createRequire } from "module";
@@ -1925,26 +1926,321 @@ ${this.logo} ${APP_NAME} is ready! (${source})`);
     const ok = await service.runJob(jobId, Boolean(opts.force));
     console.log(ok ? "\u2713 Job executed" : `Failed to run job ${jobId}`);
   }
-  status() {
+  async status(opts = {}) {
+    const report = await this.collectRuntimeStatus({
+      verbose: Boolean(opts.verbose),
+      fix: Boolean(opts.fix)
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+      process.exitCode = report.exitCode;
+      return;
+    }
+    console.log(`${this.logo} ${APP_NAME} Status`);
+    console.log(`Level: ${report.level}`);
+    console.log(`Generated: ${report.generatedAt}`);
+    console.log("");
+    const processLabel = report.process.running ? `running (PID ${report.process.pid})` : report.process.staleState ? "stale-state" : "stopped";
+    console.log(`Process: ${processLabel}`);
+    console.log(`State file: ${report.serviceStatePath} ${report.serviceStateExists ? "\u2713" : "\u2717"}`);
+    if (report.process.startedAt) {
+      console.log(`Started: ${report.process.startedAt}`);
+    }
+    console.log(`Managed health: ${report.health.managed.state} (${report.health.managed.detail})`);
+    if (!report.process.running) {
+      console.log(`Configured health: ${report.health.configured.state} (${report.health.configured.detail})`);
+    }
+    console.log(`UI: ${report.endpoints.uiUrl ?? report.endpoints.configuredUiUrl}`);
+    console.log(`API: ${report.endpoints.apiUrl ?? report.endpoints.configuredApiUrl}`);
+    console.log(`Config: ${report.configPath} ${report.configExists ? "\u2713" : "\u2717"}`);
+    console.log(`Workspace: ${report.workspacePath} ${report.workspaceExists ? "\u2713" : "\u2717"}`);
+    console.log(`Model: ${report.model}`);
+    for (const provider of report.providers) {
+      console.log(`${provider.name}: ${provider.configured ? "\u2713" : "not set"}${provider.detail ? ` (${provider.detail})` : ""}`);
+    }
+    if (report.fixActions.length > 0) {
+      console.log("");
+      console.log("Fix actions:");
+      for (const action of report.fixActions) {
+        console.log(`- ${action}`);
+      }
+    }
+    if (report.issues.length > 0) {
+      console.log("");
+      console.log("Issues:");
+      for (const issue of report.issues) {
+        console.log(`- ${issue}`);
+      }
+    }
+    if (report.recommendations.length > 0) {
+      console.log("");
+      console.log("Recommendations:");
+      for (const recommendation of report.recommendations) {
+        console.log(`- ${recommendation}`);
+      }
+    }
+    if (opts.verbose && report.logTail.length > 0) {
+      console.log("");
+      console.log("Recent logs:");
+      for (const line of report.logTail) {
+        console.log(line);
+      }
+    }
+    process.exitCode = report.exitCode;
+  }
+  async doctor(opts = {}) {
+    const report = await this.collectRuntimeStatus({
+      verbose: Boolean(opts.verbose),
+      fix: Boolean(opts.fix)
+    });
+    const checkPort = await this.checkPortAvailability({
+      host: report.process.running ? report.endpoints.uiUrl ? new URL(report.endpoints.uiUrl).hostname : "127.0.0.1" : "127.0.0.1",
+      port: (() => {
+        try {
+          const base = report.process.running && report.endpoints.uiUrl ? report.endpoints.uiUrl : report.endpoints.configuredUiUrl;
+          return Number(new URL(base).port || 80);
+        } catch {
+          return 18791;
+        }
+      })()
+    });
+    const providerConfigured = report.providers.some((provider) => provider.configured);
+    const checks = [
+      {
+        name: "config-file",
+        status: report.configExists ? "pass" : "fail",
+        detail: report.configPath
+      },
+      {
+        name: "workspace-dir",
+        status: report.workspaceExists ? "pass" : "warn",
+        detail: report.workspacePath
+      },
+      {
+        name: "service-state",
+        status: report.process.staleState ? "fail" : report.process.running ? "pass" : "warn",
+        detail: report.process.running ? `PID ${report.process.pid}` : report.process.staleState ? "state exists but process is not running" : "service not running"
+      },
+      {
+        name: "service-health",
+        status: report.process.running ? report.health.managed.state === "ok" ? "pass" : "fail" : report.health.configured.state === "ok" ? "warn" : "warn",
+        detail: report.process.running ? `${report.health.managed.state}: ${report.health.managed.detail}` : `${report.health.configured.state}: ${report.health.configured.detail}`
+      },
+      {
+        name: "ui-port-availability",
+        status: report.process.running ? "pass" : checkPort.available ? "pass" : "fail",
+        detail: report.process.running ? "managed by running service" : checkPort.available ? "available" : checkPort.detail
+      },
+      {
+        name: "provider-config",
+        status: providerConfigured ? "pass" : "warn",
+        detail: providerConfigured ? "at least one provider configured" : "no provider api key configured"
+      }
+    ];
+    const failed = checks.filter((check) => check.status === "fail");
+    const warned = checks.filter((check) => check.status === "warn");
+    const exitCode = failed.length > 0 ? 1 : warned.length > 0 ? 1 : 0;
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            generatedAt: report.generatedAt,
+            checks,
+            status: report,
+            exitCode
+          },
+          null,
+          2
+        )
+      );
+      process.exitCode = exitCode;
+      return;
+    }
+    console.log(`${this.logo} ${APP_NAME} Doctor`);
+    console.log(`Generated: ${report.generatedAt}`);
+    console.log("");
+    for (const check of checks) {
+      const icon = check.status === "pass" ? "\u2713" : check.status === "warn" ? "!" : "\u2717";
+      console.log(`${icon} ${check.name}: ${check.detail}`);
+    }
+    if (report.recommendations.length > 0) {
+      console.log("");
+      console.log("Recommendations:");
+      for (const recommendation of report.recommendations) {
+        console.log(`- ${recommendation}`);
+      }
+    }
+    if (opts.verbose && report.logTail.length > 0) {
+      console.log("");
+      console.log("Recent logs:");
+      for (const line of report.logTail) {
+        console.log(line);
+      }
+    }
+    process.exitCode = exitCode;
+  }
+  async collectRuntimeStatus(params) {
     const configPath = getConfigPath();
     const config2 = loadConfig();
-    const workspace = getWorkspacePath(config2.agents.defaults.workspace);
-    console.log(`${this.logo} ${APP_NAME} Status
-`);
-    console.log(`Config: ${configPath} ${existsSync4(configPath) ? "\u2713" : "\u2717"}`);
-    console.log(`Workspace: ${workspace} ${existsSync4(workspace) ? "\u2713" : "\u2717"}`);
-    console.log(`Model: ${config2.agents.defaults.model}`);
-    for (const spec of PROVIDERS) {
+    const workspacePath = getWorkspacePath(config2.agents.defaults.workspace);
+    const serviceStatePath = resolve4(getDataDir2(), "run", "service.json");
+    const fixActions = [];
+    let serviceState = readServiceState();
+    if (params.fix && serviceState && !isProcessRunning(serviceState.pid)) {
+      clearServiceState();
+      fixActions.push("Cleared stale service state file.");
+      serviceState = readServiceState();
+    }
+    const managedByState = Boolean(serviceState);
+    const running = Boolean(serviceState && isProcessRunning(serviceState.pid));
+    const staleState = Boolean(serviceState && !running);
+    const configuredUi = resolveUiConfig(config2, { enabled: true, host: config2.ui.host, port: config2.ui.port });
+    const configuredUiUrl = resolveUiApiBase(configuredUi.host, configuredUi.port);
+    const configuredApiUrl = `${configuredUiUrl}/api`;
+    const managedUiUrl = serviceState?.uiUrl ?? null;
+    const managedApiUrl = serviceState?.apiUrl ?? null;
+    const managedHealth = running && managedApiUrl ? await this.probeApiHealth(`${managedApiUrl}/health`) : { state: "unreachable", detail: "service not running" };
+    const configuredHealth = await this.probeApiHealth(`${configuredApiUrl}/health`, 900);
+    const orphanSuspected = !running && configuredHealth.state === "ok";
+    const providers = PROVIDERS.map((spec) => {
       const provider = config2.providers[spec.name];
       if (!provider) {
-        continue;
+        return { name: spec.displayName ?? spec.name, configured: false, detail: "missing config" };
       }
       if (spec.isLocal) {
-        console.log(`${spec.displayName ?? spec.name}: ${provider.apiBase ? `\u2713 ${provider.apiBase}` : "not set"}`);
-      } else {
-        console.log(`${spec.displayName ?? spec.name}: ${provider.apiKey ? "\u2713" : "not set"}`);
+        return {
+          name: spec.displayName ?? spec.name,
+          configured: Boolean(provider.apiBase),
+          detail: provider.apiBase ? provider.apiBase : "apiBase not set"
+        };
       }
+      return {
+        name: spec.displayName ?? spec.name,
+        configured: Boolean(provider.apiKey),
+        detail: provider.apiKey ? "apiKey set" : "apiKey not set"
+      };
+    });
+    const issues = [];
+    const recommendations = [];
+    if (!existsSync4(configPath)) {
+      issues.push("Config file is missing.");
+      recommendations.push(`Run ${APP_NAME} init to create config files.`);
     }
+    if (!existsSync4(workspacePath)) {
+      issues.push("Workspace directory does not exist.");
+      recommendations.push(`Run ${APP_NAME} init to create workspace templates.`);
+    }
+    if (staleState) {
+      issues.push("Service state is stale (state exists but process is not running).");
+      recommendations.push(`Run ${APP_NAME} status --fix to clean stale state.`);
+    }
+    if (running && managedHealth.state !== "ok") {
+      issues.push(`Managed service health check failed: ${managedHealth.detail}`);
+      recommendations.push(`Check logs at ${serviceState?.logPath ?? resolveServiceLogPath()}.`);
+    }
+    if (!running) {
+      recommendations.push(`Run ${APP_NAME} start to launch the service.`);
+    }
+    if (orphanSuspected) {
+      issues.push("A service appears healthy on configured API endpoint, but state is missing/stale.");
+      recommendations.push("Another process may be occupying the UI port; stop it or use --ui-port with a free port.");
+    }
+    if (!providers.some((provider) => provider.configured)) {
+      recommendations.push("Configure at least one provider API key in UI or config before expecting agent replies.");
+    }
+    const logTail = params.verbose ? this.readLogTail(serviceState?.logPath ?? resolveServiceLogPath(), 25) : [];
+    const level = running ? managedHealth.state === "ok" ? issues.length > 0 ? "degraded" : "healthy" : "degraded" : "stopped";
+    const exitCode = level === "healthy" ? 0 : level === "degraded" ? 1 : 2;
+    return {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      configPath,
+      configExists: existsSync4(configPath),
+      workspacePath,
+      workspaceExists: existsSync4(workspacePath),
+      model: config2.agents.defaults.model,
+      providers,
+      serviceStatePath,
+      serviceStateExists: existsSync4(serviceStatePath),
+      fixActions,
+      process: {
+        managedByState,
+        pid: serviceState?.pid ?? null,
+        running,
+        staleState,
+        orphanSuspected,
+        startedAt: serviceState?.startedAt ?? null
+      },
+      endpoints: {
+        uiUrl: managedUiUrl,
+        apiUrl: managedApiUrl,
+        configuredUiUrl,
+        configuredApiUrl
+      },
+      health: {
+        managed: managedHealth,
+        configured: configuredHealth
+      },
+      issues,
+      recommendations,
+      logTail,
+      level,
+      exitCode
+    };
+  }
+  async probeApiHealth(url, timeoutMs = 1500) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        return { state: "invalid-response", detail: `HTTP ${response.status}` };
+      }
+      const payload = await response.json();
+      if (payload?.ok === true && payload?.data?.status === "ok") {
+        return { state: "ok", detail: "health endpoint returned ok", payload };
+      }
+      return { state: "invalid-response", detail: "unexpected health payload", payload };
+    } catch (error) {
+      return { state: "unreachable", detail: String(error) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  readLogTail(path, maxLines = 25) {
+    if (!existsSync4(path)) {
+      return [];
+    }
+    try {
+      const lines = readFileSync3(path, "utf-8").split(/\r?\n/).filter(Boolean);
+      if (lines.length <= maxLines) {
+        return lines;
+      }
+      return lines.slice(lines.length - maxLines);
+    } catch {
+      return [];
+    }
+  }
+  async checkPortAvailability(params) {
+    return await new Promise((resolve5) => {
+      const server = createNetServer();
+      server.once("error", (error) => {
+        resolve5({
+          available: false,
+          detail: `bind failed on ${params.host}:${params.port} (${String(error)})`
+        });
+      });
+      server.listen(params.port, params.host, () => {
+        server.close(() => {
+          resolve5({
+            available: true,
+            detail: `bind ok on ${params.host}:${params.port}`
+          });
+        });
+      });
+    });
   }
   loadPluginRegistry(config2, workspaceDir) {
     return loadOpenClawPlugins({
@@ -2490,6 +2786,7 @@ ${this.logo} ${APP_NAME} is ready! (${source})`);
       { source: "USER.md", target: "USER.md" },
       { source: "IDENTITY.md", target: "IDENTITY.md" },
       { source: "TOOLS.md", target: "TOOLS.md" },
+      { source: "USAGE.md", target: "USAGE.md" },
       { source: "BOOT.md", target: "BOOT.md" },
       { source: "BOOTSTRAP.md", target: "BOOTSTRAP.md" },
       { source: "HEARTBEAT.md", target: "HEARTBEAT.md" },
@@ -2534,10 +2831,6 @@ ${this.logo} ${APP_NAME} is ready! (${source})`);
       return 0;
     }
     const force = Boolean(options.force);
-    const existing = readdirSync(targetDir, { withFileTypes: true }).filter((entry) => !entry.name.startsWith("."));
-    if (!force && existing.length > 0) {
-      return 0;
-    }
     let seeded = 0;
     for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) {
@@ -2685,5 +2978,6 @@ cron.command("add").requiredOption("-n, --name <name>", "Job name").requiredOpti
 cron.command("remove <jobId>").action((jobId) => runtime.cronRemove(jobId));
 cron.command("enable <jobId>").option("--disable", "Disable instead of enable").action((jobId, opts) => runtime.cronEnable(jobId, opts));
 cron.command("run <jobId>").option("-f, --force", "Run even if disabled").action(async (jobId, opts) => runtime.cronRun(jobId, opts));
-program.command("status").description(`Show ${APP_NAME2} status`).action(() => runtime.status());
+program.command("status").description(`Show ${APP_NAME2} status`).option("--json", "Output JSON", false).option("--verbose", "Show extra diagnostics", false).option("--fix", "Fix stale service state when safe", false).action(async (opts) => runtime.status(opts));
+program.command("doctor").description(`Run ${APP_NAME2} diagnostics`).option("--json", "Output JSON", false).option("--verbose", "Show extra diagnostics", false).option("--fix", "Fix stale service state when safe", false).action(async (opts) => runtime.doctor(opts));
 program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextclaw",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Lightweight personal AI assistant with CLI, multi-provider routing, and channel integrations.",
   "private": false,
   "type": "module",
@@ -38,7 +38,7 @@
   "dependencies": {
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
-    "@nextclaw/core": "^0.5.1",
+    "@nextclaw/core": "^0.5.2",
     "@nextclaw/server": "^0.3.7",
     "@nextclaw/openclaw-compat": "^0.1.3"
   },
@@ -57,7 +57,7 @@
   "scripts": {
     "dev": "tsx watch --tsconfig tsconfig.json src/cli/index.ts",
     "dev:build": "tsx src/cli/index.ts",
-    "build": "tsup src/index.ts src/cli/index.ts --format esm --dts --out-dir dist && node scripts/copy-ui-dist.mjs",
+    "build": "node scripts/sync-usage-template.mjs && tsup src/index.ts src/cli/index.ts --format esm --dts --out-dir dist && node scripts/copy-ui-dist.mjs",
     "start": "node dist/cli.js",
     "lint": "eslint .",
     "tsc": "tsc -p tsconfig.json",

package/templates/AGENTS.md

@@ -14,6 +14,7 @@ Before doing anything else:
 2. Read `USER.md` (who you are helping)
 3. Read `memory/YYYY-MM-DD.md` for today and yesterday
 4. If in the main session with your human, also read `MEMORY.md`
+5. For NextClaw self-management tasks (service/plugins/channels/config/cron), read `USAGE.md` first
 
 ## Memory
 

package/templates/USAGE.md

@@ -0,0 +1,616 @@
+<!-- Generated by packages/nextclaw/scripts/sync-usage-template.mjs -->
+<!-- Do not edit this file directly; edit docs/USAGE.md instead. -->
+# NextClaw User Guide
+
+This guide covers installation, configuration, channels, tools, automation, and troubleshooting for NextClaw.
+
+---
+
+## AI Self-Management Contract
+
+When NextClaw AI needs to operate the product itself (status/doctor/plugins/channels/config/cron), follow these rules:
+
+1. **Read this guide first** (`USAGE.md`) before executing management commands.
+2. **Prefer machine-readable output** (`--json`) whenever available.
+3. **Close the loop after changes** with `nextclaw status --json` (and `nextclaw doctor --json` when needed).
+4. **Be explicit about restart semantics** (hot-apply, auto-restart, or manual restart required).
+5. **Never invent commands**; use documented commands or `nextclaw --help` / `nextclaw <subcommand> --help`.
+
+---
+
+## Table of contents
+
+- [AI Self-Management Contract](#ai-self-management-contract)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Workspace](#workspace)
+- [Commands](#commands)
+- [Plugins (OpenClaw compatibility)](#plugins-openclaw-compatibility)
+- [Channels](#channels)
+- [Tools](#tools)
+- [Cron & Heartbeat](#cron--heartbeat)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start
+
+1. Install:
+
+   ```bash
+   npm i -g nextclaw
+   ```
+
+2. Start the service (gateway + config UI in the background):
+
+   ```bash
+   nextclaw start
+   ```
+
+3. Open **http://127.0.0.1:18791** in your browser. Set a provider (e.g. OpenRouter) and model in the UI.
+
+4. Optionally run `nextclaw init` to create a workspace with agent templates, or chat from the CLI:
+
+   ```bash
+   nextclaw agent -m "Hello!"
+   ```
+
+5. Stop the service when done:
+
+   ```bash
+   nextclaw stop
+   ```
+
+---
+
+## Configuration
+
+- **Config file:** `~/.nextclaw/config.json`
+- **Data directory:** Override with `NEXTCLAW_HOME=/path/to/dir` (config path becomes `$NEXTCLAW_HOME/config.json`).
+
+### Minimal config
+
+```json
+{
+  "providers": {
+    "openrouter": { "apiKey": "sk-or-v1-xxx" }
+  },
+  "agents": {
+    "defaults": { "model": "minimax/MiniMax-M2.5" }
+  }
+}
+```
+
+### Provider examples
+
+**OpenRouter (recommended)**
+
+```json
+{
+  "providers": { "openrouter": { "apiKey": "sk-or-v1-xxx" } },
+  "agents": { "defaults": { "model": "minimax/MiniMax-M2.5" } }
+}
+```
+
+**MiniMax (Mainland China)**
+
+```json
+{
+  "providers": {
+    "minimax": {
+      "apiKey": "sk-api-xxx",
+      "apiBase": "https://api.minimaxi.com/v1"
+    }
+  },
+  "agents": { "defaults": { "model": "minimax/MiniMax-M2.5" } }
+}
+```
+
+**Local vLLM (or any OpenAI-compatible server)**
+
+```json
+{
+  "providers": {
+    "vllm": {
+      "apiKey": "dummy",
+      "apiBase": "http://localhost:8000/v1"
+    }
+  },
+  "agents": { "defaults": { "model": "meta-llama/Llama-3.1-8B-Instruct" } }
+}
+```
+
+Supported providers include OpenRouter, OpenAI, Anthropic, MiniMax, Moonshot, Gemini, DeepSeek, DashScope, Zhipu, Groq, vLLM, and AiHubMix. You can configure them in the UI or by editing `config.json`.
+
+### Runtime config apply behavior (no restart)
+
+When the gateway is already running, config changes from the UI or `nextclaw config set` are hot-applied for these paths:
+
+- `providers.*`
+- `channels.*`
+- `agents.defaults.model`
+- `agents.defaults.maxToolIterations`
+- `agents.defaults.maxTokens`
+- `agents.defaults.temperature`
+- `agents.context.*`
+- `tools.*`
+
+Restart is still required for:
+
+- `plugins.*`
+- UI bind port (`--port` / `--ui-port`)
+
+To confirm hot reload succeeded, check gateway console logs or `${NEXTCLAW_HOME:-~/.nextclaw}/logs/service.log` for messages like `Config reload: ... applied.`
+
+---
+
+## Workspace
+
+- **Default path:** `~/.nextclaw/workspace`
+- Override in config:
+
+  ```json
+  {
+    "agents": { "defaults": { "workspace": "~/my-nextclaw" } }
+  }
+  ```
+
+Initialize the workspace (creates template files if missing):
+
+```bash
+nextclaw init
+```
+
+Use `nextclaw init --force` to overwrite existing template files.
+
+Created under the workspace:
+
+| File / folder   | Purpose                          |
+|-----------------|----------------------------------|
+| `AGENTS.md`     | System instructions for the agent |
+| `SOUL.md`       | Personality and values            |
+| `USER.md`       | User profile hints                |
+| `IDENTITY.md`   | Identity context                  |
+| `TOOLS.md`      | Tool usage guidelines             |
+| `USAGE.md`      | CLI operation guide for users and AI |
+| `BOOT.md` / `BOOTSTRAP.md` | Boot context               |
+| `HEARTBEAT.md`  | Tasks checked periodically        |
+| `memory/MEMORY.md` | Long-term notes                |
+| `skills/`       | Custom skills                     |
+
+**Heartbeat:** When the gateway is running, `HEARTBEAT.md` in the workspace is checked every 30 minutes. If it contains actionable tasks, the agent will process them.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `nextclaw start` | Start gateway + UI in the background |
+| `nextclaw restart` | Restart the background service with optional start flags |
+| `nextclaw stop` | Stop the background service |
+| `nextclaw ui` | Start UI and gateway in the foreground |
+| `nextclaw gateway` | Start gateway only (for channels) |
+| `nextclaw serve` | Run gateway + UI in the foreground (no background) |
+| `nextclaw agent -m "message"` | Send a one-off message to the agent |
+| `nextclaw agent` | Interactive chat in the terminal |
+| `nextclaw status` | Show runtime process/health/config status (`--json`, `--verbose`, `--fix`) |
+| `nextclaw init` | Initialize workspace and template files |
+| `nextclaw init --force` | Re-run init and overwrite templates |
+| `nextclaw update` | Self-update the CLI |
+| `nextclaw channels status` | Show enabled channels and status |
+| `nextclaw doctor` | Run runtime diagnostics (`--json`, `--verbose`, `--fix`) |
+| `nextclaw channels login` | Open QR login for supported channels |
+| `nextclaw channels add --channel <id> [--code/--token/...]` | Run plugin channel setup (OpenClaw-compatible) and write config |
+| `nextclaw cron list` | List scheduled jobs |
+| `nextclaw cron add ...` | Add a cron job (see [Cron](#cron--heartbeat)) |
+| `nextclaw cron remove <jobId>` | Remove a job |
+| `nextclaw cron enable <jobId>` | Enable a job (use `--disable` to disable) |
+| `nextclaw cron run <jobId>` | Run a job once (optionally with `--force` if disabled) |
+| `nextclaw skills install <slug>` | Install a skill from ClawHub |
+| `nextclaw clawhub install <slug>` | Same as `skills install` |
+| `nextclaw plugins list` | List discovered OpenClaw-compatible plugins |
+| `nextclaw plugins info <id>` | Show details of a plugin |
+| `nextclaw config get <path>` | Get config value by path (use `--json` for structured output) |
+| `nextclaw config set <path> <value>` | Set config value by path (use `--json` to parse value as JSON) |
+| `nextclaw config unset <path>` | Remove config value by path |
+| `nextclaw plugins install <path-or-spec>` | Install from local path, archive, or npm package |
+| `nextclaw plugins enable <id>` | Enable a plugin in config |
+| `nextclaw plugins disable <id>` | Disable a plugin in config |
+| `nextclaw plugins uninstall <id>` | Remove plugin config/install record (supports `--dry-run`, `--force`, `--keep-files`) |
+| `nextclaw plugins doctor` | Diagnose plugin load conflicts/errors |
+
+Gateway options (when running `nextclaw gateway` or `nextclaw start`):
+
+- `--ui` — enable the UI server with the gateway
+- `--ui-port <port>` — UI port (default 18791 for start)
+- `--ui-open` — open the browser when the UI starts
+
+If service is already running, new UI port flags do not hot-apply; use `nextclaw restart ...` to apply them.
+
+Status/diagnostics tips:
+
+- `nextclaw status` shows runtime truth (process + health + config summary).
+- `nextclaw status --json` outputs machine-readable status and sets exit code (`0` healthy, `1` degraded, `2` stopped).
+- `nextclaw status --fix` safely clears stale service state if PID is dead.
+- `nextclaw doctor` runs additional checks (state coherence, health, port availability, provider readiness).
+
+---
+
+## Plugins (OpenClaw compatibility)
+
+NextClaw supports OpenClaw-compatible plugins while keeping compatibility logic isolated in `@nextclaw/openclaw-compat`.
+For architecture boundaries and capability matrix, see [OpenClaw plugin compatibility guide](./openclaw-plugin-compat.md).
+
+Typical flow:
+
+```bash
+# 1) Inspect discovered plugins
+nextclaw plugins list
+
+# 2) Install (path/archive/npm)
+nextclaw plugins install ./my-plugin
+nextclaw plugins install ./my-plugin.tgz
+nextclaw plugins install @scope/openclaw-plugin
+
+# 3) Inspect and toggle
+nextclaw plugins info my-plugin
+nextclaw config get plugins.entries.my-plugin.config --json
+nextclaw plugins disable my-plugin
+nextclaw plugins enable my-plugin
+
+# 4) Uninstall
+nextclaw plugins uninstall my-plugin --dry-run
+nextclaw plugins uninstall my-plugin --force
+```
+
+Notes:
+
+- Plugin config is merged under `plugins.entries.<id>.config`.
+- `plugins uninstall --keep-config` is accepted as a backward-compatible alias of `--keep-files`.
+- If a plugin tool/channel/provider conflicts with a built-in capability, NextClaw rejects the conflicting registration and reports diagnostics.
+
+---
+
+## Self-update
+
+Use the built-in updater:
+
+```bash
+nextclaw update
+```
+
+Behavior:
+
+- If `NEXTCLAW_UPDATE_COMMAND` is set, the CLI executes it (useful for custom update flows).
+- Otherwise it falls back to `npm i -g nextclaw`.
+- If the background service is running, restart it after the update to apply changes.
+
+If the gateway is running, you can also ask the agent to update; the agent will call the gateway update tool only when you explicitly request it, and a restart will be scheduled afterward.
+
+---
+
+## Channels
+
+All message channels use a common **allowFrom** rule:
+
+- **Empty `allowFrom`** (`[]`): allow all senders.
+- **Non-empty `allowFrom`**: only messages from the listed user IDs are accepted.
+
+Configure channels in the UI at http://127.0.0.1:18791 or in `~/.nextclaw/config.json` under `channels`.
+
+### Discord
+
+1. Create a bot in the [Discord Developer Portal](https://discord.com/developers/applications) and get the bot token.
+2. Enable **MESSAGE CONTENT INTENT** for the bot.
+3. Invite the bot to your server with permissions to read and send messages.
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": []
+    }
+  }
+}
+```
+
+### Telegram
+
+1. Create a bot via [@BotFather](https://t.me/BotFather) and get the token.
+2. Get your user ID (e.g. from [@userinfobot](https://t.me/userinfobot)).
+3. Add your user ID to `allowFrom` to restrict who can use the bot.
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+Optional: set `"proxy": "http://localhost:7890"` (or your proxy URL) for network access.
+
+### Slack
+
+Socket mode is the typical setup. You need a **Bot Token** and an **App-Level Token** (with `connections:write`).
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "mode": "socket",
+      "botToken": "xoxb-...",
+      "appToken": "xapp-...",
+      "dm": { "enabled": true, "allowFrom": [] }
+    }
+  }
+}
+```
+
+- `dm.enabled`: allow DMs to the bot.
+- `dm.allowFrom`: restrict DMs to these user IDs; empty means allow all.
+
+### Feishu (Lark)
+
+Create an app in the [Feishu open platform](https://open.feishu.com/), obtain App ID, App Secret, and (if using encryption) Encrypt Key and Verification Token.
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "appId": "YOUR_APP_ID",
+      "appSecret": "YOUR_APP_SECRET",
+      "encryptKey": "",
+      "verificationToken": "",
+      "allowFrom": []
+    }
+  }
+}
+```
+
+### DingTalk
+
+Create an app in the [DingTalk open platform](https://open.dingtalk.com/) and get Client ID and Client Secret.
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "clientId": "YOUR_CLIENT_ID",
+      "clientSecret": "YOUR_CLIENT_SECRET",
+      "allowFrom": []
+    }
+  }
+}
+```
+
+### WhatsApp
+
+WhatsApp typically requires a bridge (e.g. a companion service). Configure the bridge URL and optional allowlist:
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "bridgeUrl": "ws://localhost:3001",
+      "allowFrom": []
+    }
+  }
+}
+```
+
+Use `nextclaw channels login` when the bridge supports QR-based linking.
+
+### Email
+
+Configure IMAP (inbox) and SMTP (sending). The agent can read and reply to emails.
+
+```json
+{
+  "channels": {
+    "email": {
+      "enabled": true,
+      "consentGranted": true,
+      "imapHost": "imap.example.com",
+      "imapPort": 993,
+      "imapUsername": "you@example.com",
+      "imapPassword": "YOUR_PASSWORD",
+      "imapMailbox": "INBOX",
+      "imapUseSsl": true,
+      "smtpHost": "smtp.example.com",
+      "smtpPort": 587,
+      "smtpUsername": "you@example.com",
+      "smtpPassword": "YOUR_PASSWORD",
+      "smtpUseTls": true,
+      "fromAddress": "you@example.com",
+      "autoReplyEnabled": true,
+      "pollIntervalSeconds": 30,
+      "allowFrom": []
+    }
+  }
+}
+```
+
+Set `consentGranted` to `true` after you understand that the agent will read and send mail. Use `allowFrom` to restrict to certain sender addresses if desired.
+
+### QQ
+
+Use the QQ open platform app credentials.
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "appId": "YOUR_APP_ID",
+      "secret": "YOUR_SECRET",
+      "markdownSupport": false,
+      "allowFrom": []
+    }
+  }
+}
+```
+
+### Mochat
+
+Mochat uses a claw token and optional socket URL. Configure base URL, socket, and (optionally) sessions/panels and group rules.
+
+```json
+{
+  "channels": {
+    "mochat": {
+      "enabled": true,
+      "baseUrl": "https://mochat.io",
+      "socketUrl": "",
+      "clawToken": "YOUR_CLAW_TOKEN",
+      "agentUserId": "",
+      "sessions": [],
+      "panels": [],
+      "allowFrom": []
+    }
+  }
+}
+```
+
+After changing channel config, NextClaw hot-reloads channel runtime automatically when the gateway is running.
+
+---
+
+## Tools
+
+### Web search (Brave)
+
+Add a Brave Search API key to enable web search for the agent:
+
+```json
+{
+  "tools": {
+    "web": {
+      "search": { "apiKey": "YOUR_BRAVE_KEY", "maxResults": 5 }
+    }
+  }
+}
+```
+
+### Command execution (exec)
+
+Allow the agent to run shell commands:
+
+```json
+{
+  "tools": {
+    "exec": { "timeout": 60 }
+  },
+  "restrictToWorkspace": false
+}
+```
+
+- `timeout`: max seconds per command.
+- `restrictToWorkspace`: if `true`, commands are restricted to the agent workspace directory; if `false`, the agent can run commands in other paths (use with care).
+
+---
+
+## Cron & Heartbeat
+
+### Cron
+
+Schedule one-off or recurring tasks. The agent receives the message at the scheduled time.
+
+List jobs:
+
+```bash
+nextclaw cron list
+```
+
+Add a one-time job (run at a specific time, ISO format):
+
+```bash
+nextclaw cron add -n "reminder" -m "Stand up and stretch" --at "2026-02-15T09:00:00"
+```
+
+Add a recurring job (cron expression):
+
+```bash
+nextclaw cron add -n "daily-summary" -m "Summarize yesterday" -c "0 9 * * *"
+```
+
+Add a job that runs every N seconds:
+
+```bash
+nextclaw cron add -n "ping" -m "Ping" -e 3600
+```
+
+Optional: deliver the agent’s reply to a channel:
+
+```bash
+nextclaw cron add -n "daily" -m "Daily briefing" -c "0 9 * * *" --deliver --to <recipient> --channel <channel>
+```
+
+Remove, enable, or disable a job:
+
+```bash
+nextclaw cron remove <jobId>
+nextclaw cron enable <jobId>
+nextclaw cron enable <jobId> --disable
+```
+
+Run a job once (e.g. for testing):
+
+```bash
+nextclaw cron run <jobId>
+```
+
+### Heartbeat
+
+When the gateway is running, it checks the workspace file `HEARTBEAT.md` periodically (e.g. every 30 minutes). If the file contains actionable tasks, the agent processes them. Edit `HEARTBEAT.md` in your workspace to add or change tasks.
+
+---
+
+## UI (optional)
+
+You can tune the UI server in config:
+
+```json
+{
+  "ui": {
+    "enabled": true,
+    "host": "0.0.0.0",
+    "port": 18791,
+    "open": false
+  }
+}
+```
+
+- `enabled`: whether the UI server is started with the gateway (e.g. when using `nextclaw start`).
+- `host` / `port`: bind address and port; `ui.host` is read-only in practice (CLI start paths always enforce `0.0.0.0`).
+- `open`: open the default browser when the UI starts.
+
+Default URL when using `nextclaw start`: **http://127.0.0.1:18791**.
+
+NextClaw binds UI to `0.0.0.0` by default and attempts to detect/print a public IP-based URL at startup.
+
+---
+
+## Troubleshooting
+
+| Issue | What to check |
+|-------|----------------|
+| **401 / invalid API key** | Verify the provider `apiKey` and `apiBase` in config or UI. Ensure no extra spaces or wrong key. |
+| **Unknown model** | Confirm the model ID is supported by your provider (e.g. OpenRouter model list). |
+| **No replies on a channel** | Ensure the channel is `enabled`, `allowFrom` includes your user ID if set, and the gateway is running (`nextclaw start` or `nextclaw gateway`). Run `nextclaw channels status` to see channel status. |
+| **Port already in use** | Change `ui.port` in config or use `--ui-port` when starting. Default UI port is 18791, gateway 18790. |
+| **Config not loading** | Ensure `NEXTCLAW_HOME` (if set) points to the directory that contains `config.json`. Run `nextclaw status` to see which config file is used. |
+| **Agent not responding in CLI** | Run `nextclaw init` if you have not yet; ensure a provider and model are set and the provider key is valid. |
+
+---