@jhytabest/plashboard 0.1.4 → 0.1.6

package/README.md

@@ -35,7 +35,8 @@ Add to `openclaw.json`:
           "default_retry_count": 1,
           "retry_backoff_seconds": 20,
           "session_timeout_seconds": 90,
-          "fill_provider": "mock",
+          "fill_provider": "openclaw",
+          "openclaw_fill_agent_id": "main",
           "display_profile": {
             "width_px": 1920,
             "height_px": 1080,
@@ -51,11 +52,15 @@ Add to `openclaw.json`:
 }
 ```
 
-For real model runs, switch `fill_provider` to `command` and provide `fill_command`.
+`fill_provider: "openclaw"` is the default real mode and calls `openclaw agent` directly.
+Use `fill_provider: "command"` only if you need a custom external runner.
 
 ## Runtime Command
 
 ```text
+/plashboard setup [openclaw [agent_id]|mock|command <fill_command>]
+/plashboard expose-guide [local_url] [https_port]
+/plashboard expose-check [local_url] [https_port]
 /plashboard init
 /plashboard status
 /plashboard list
@@ -66,6 +71,20 @@ For real model runs, switch `fill_provider` to `command` and provide `fill_comma
 /plashboard set-display <width> <height> <safe_top> <safe_bottom>
 ```
 
+Recommended first run:
+
+```text
+/plashboard setup openclaw
+/plashboard init
+```
+
+Tailscale helper flow:
+
+```text
+/plashboard expose-guide
+/plashboard expose-check
+```
+
 ## Notes
 
 - The plugin includes an admin skill (`plashboard-admin`) for tool-guided management.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "plashboard",
   "name": "Plashboard",
-  "version": "0.1.0",
+  "version": "0.1.6",
   "description": "Template-driven dashboard runtime with scheduled OpenClaw fills and safe publish.",
   "entry": "./src/index.ts",
   "skills": ["./skills/plashboard-admin"],
@@ -15,8 +15,9 @@
       "default_retry_count": { "type": "integer", "minimum": 0, "maximum": 5, "default": 1 },
       "retry_backoff_seconds": { "type": "integer", "minimum": 1, "maximum": 300, "default": 20 },
       "session_timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 600, "default": 90 },
-      "fill_provider": { "type": "string", "enum": ["command", "mock"], "default": "mock" },
+      "fill_provider": { "type": "string", "enum": ["command", "mock", "openclaw"], "default": "openclaw" },
       "fill_command": { "type": "string" },
+      "openclaw_fill_agent_id": { "type": "string", "default": "main" },
       "python_bin": { "type": "string", "default": "python3" },
       "writer_script_path": { "type": "string" },
       "dashboard_output_path": { "type": "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhytabest/plashboard",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "description": "Plashboard OpenClaw plugin runtime",
   "license": "MIT",

package/skills/plashboard-admin/SKILL.md

@@ -17,6 +17,9 @@ Use this skill for plashboard runtime administration.
 
 ## Required Tooling
 Always use plugin tools:
+- `plashboard_setup`
+- `plashboard_exposure_guide`
+- `plashboard_exposure_check`
 - `plashboard_init`
 - `plashboard_template_create`
 - `plashboard_template_update`
@@ -36,6 +39,9 @@ Always use plugin tools:
 - Never ask the model to generate full dashboard structure when filling values.
 
 ## Command Shortcuts
+- `/plashboard setup [openclaw [agent_id]|mock|command <fill_command>]`
+- `/plashboard expose-guide [local_url] [https_port]`
+- `/plashboard expose-check [local_url] [https_port]`
 - `/plashboard init`
 - `/plashboard status`
 - `/plashboard list`

package/src/config.ts

@@ -50,8 +50,12 @@ export function resolveConfig(api: unknown): PlashboardConfig {
 
   const dataDir = asString(raw.data_dir, '/var/lib/openclaw/plash-data');
   const outputPath = asString(raw.dashboard_output_path, join(dataDir, 'dashboard.json'));
-  const fillProviderRaw = asString(raw.fill_provider, 'mock');
-  const fillProvider = fillProviderRaw === 'command' ? 'command' : 'mock';
+  const fillProviderRaw = asString(raw.fill_provider, 'openclaw');
+  const fillProvider = fillProviderRaw === 'command'
+    ? 'command'
+    : fillProviderRaw === 'mock'
+      ? 'mock'
+      : 'openclaw';
 
   return {
     data_dir: dataDir,
@@ -63,6 +67,7 @@ export function resolveConfig(api: unknown): PlashboardConfig {
     session_timeout_seconds: Math.max(10, Math.floor(asNumber(raw.session_timeout_seconds, 90))),
     fill_provider: fillProvider,
     fill_command: typeof raw.fill_command === 'string' ? raw.fill_command : undefined,
+    openclaw_fill_agent_id: asString(raw.openclaw_fill_agent_id, 'main'),
     python_bin: asString(raw.python_bin, 'python3'),
     writer_script_path: asString(raw.writer_script_path, DEFAULT_WRITER_PATH),
     dashboard_output_path: outputPath,

package/src/fill-runner.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createFillRunner } from './fill-runner.js';
+import type { DashboardTemplate, FillRunContext, PlashboardConfig } from './types.js';
+
+function template(): DashboardTemplate {
+  return {
+    id: 'ops',
+    name: 'Ops',
+    enabled: true,
+    schedule: {
+      mode: 'interval',
+      every_minutes: 5,
+      timezone: 'UTC'
+    },
+    base_dashboard: {
+      title: 'Ops',
+      summary: 'old summary'
+    },
+    fields: [
+      {
+        id: 'summary',
+        pointer: '/summary',
+        type: 'string',
+        prompt: 'Summarize current status',
+        required: true
+      }
+    ]
+  };
+}
+
+function config(overrides: Partial<PlashboardConfig>): PlashboardConfig {
+  return {
+    data_dir: '/tmp/plash-test',
+    timezone: 'UTC',
+    scheduler_tick_seconds: 30,
+    max_parallel_runs: 1,
+    default_retry_count: 0,
+    retry_backoff_seconds: 1,
+    session_timeout_seconds: 30,
+    fill_provider: 'mock',
+    fill_command: undefined,
+    openclaw_fill_agent_id: 'main',
+    python_bin: 'python3',
+    writer_script_path: '/tmp/writer.py',
+    dashboard_output_path: '/tmp/dashboard.json',
+    layout_overflow_tolerance_px: 40,
+    display_profile: {
+      width_px: 1920,
+      height_px: 1080,
+      safe_top_px: 96,
+      safe_bottom_px: 106,
+      safe_side_px: 28,
+      layout_safety_margin_px: 24
+    },
+    model_defaults: {},
+    ...overrides
+  };
+}
+
+function context(): FillRunContext {
+  return {
+    template: template(),
+    currentValues: { summary: 'old summary' },
+    attempt: 1
+  };
+}
+
+describe('createFillRunner', () => {
+  it('parses openclaw json envelope output', async () => {
+    const commandRunner = vi.fn(async (_argv: string[], _options: unknown) => ({
+      stdout: JSON.stringify({
+        result: {
+          payloads: [
+            {
+              text: '{"values":{"summary":"new summary"}}'
+            }
+          ]
+        }
+      }),
+      stderr: '',
+      code: 0
+    }));
+
+    const runner = createFillRunner(
+      config({ fill_provider: 'openclaw', openclaw_fill_agent_id: 'ops' }),
+      { commandRunner }
+    );
+    const response = await runner.run(context());
+
+    expect(response.values.summary).toBe('new summary');
+    expect(commandRunner).toHaveBeenCalledTimes(1);
+    const firstCall = commandRunner.mock.calls[0];
+    const argv = firstCall[0];
+    expect(argv.slice(0, 2)).toEqual(['openclaw', 'agent']);
+    expect(argv).toContain('--agent');
+    expect(argv).toContain('ops');
+  });
+
+  it('parses command runner fenced json output', async () => {
+    const commandRunner = vi.fn(async (_argv: string[], _options: unknown) => ({
+      stdout: '```json\n{"values":{"summary":"from command"}}\n```',
+      stderr: '',
+      code: 0
+    }));
+
+    const runner = createFillRunner(
+      config({ fill_provider: 'command', fill_command: 'echo "$PLASHBOARD_PROMPT_JSON"' }),
+      { commandRunner }
+    );
+    const response = await runner.run(context());
+
+    expect(response.values.summary).toBe('from command');
+    expect(commandRunner).toHaveBeenCalledTimes(1);
+    const firstCall = commandRunner.mock.calls[0];
+    const argv = firstCall[0];
+    expect(argv.slice(0, 2)).toEqual(['sh', '-lc']);
+    const options = firstCall[1] as { env?: Record<string, string> };
+    expect(options.env?.PLASHBOARD_PROMPT_JSON).toContain('"template"');
+  });
+});

package/src/fill-runner.ts

@@ -1,6 +1,30 @@
 import { spawn } from 'node:child_process';
 import type { FillResponse, FillRunContext, FillRunner, PlashboardConfig } from './types.js';
 
+type CommandOptions = {
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+  input?: string;
+};
+
+export type CommandRunResult = {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: 'exit' | 'timeout' | 'signal' | string;
+};
+
+export type CommandRunner = (
+  argv: string[],
+  optionsOrTimeout: number | CommandOptions
+) => Promise<CommandRunResult>;
+
+export interface FillRunnerDeps {
+  commandRunner?: CommandRunner;
+}
+
 function buildPromptPayload(context: FillRunContext): Record<string, unknown> {
   return {
     instructions: {
@@ -32,6 +56,16 @@ function buildPromptPayload(context: FillRunContext): Record<string, unknown> {
   };
 }
 
+function buildOpenClawMessage(context: FillRunContext): string {
+  const payload = buildPromptPayload(context);
+  return [
+    'Fill dashboard fields from the provided template context.',
+    'Return exactly one JSON object with this shape: {"values": {...}}.',
+    'Do not include markdown, comments, explanations, or extra keys.',
+    JSON.stringify(payload)
+  ].join('\n\n');
+}
+
 function mockValue(type: string, currentValue: unknown, fieldId: string): unknown {
   if (type === 'number') return typeof currentValue === 'number' ? currentValue : 0;
   if (type === 'boolean') return typeof currentValue === 'boolean' ? currentValue : false;
@@ -40,30 +74,35 @@ function mockValue(type: string, currentValue: unknown, fieldId: string): unknow
   return `updated ${fieldId} at ${now}`;
 }
 
-class MockFillRunner implements FillRunner {
-  async run(context: FillRunContext): Promise<FillResponse> {
-    const values: Record<string, unknown> = {};
-    for (const field of context.template.fields) {
-      values[field.id] = mockValue(field.type, context.currentValues[field.id], field.id);
-    }
-    return { values };
+function normalizeCommandOptions(optionsOrTimeout: number | CommandOptions): CommandOptions {
+  if (typeof optionsOrTimeout === 'number') {
+    return { timeoutMs: optionsOrTimeout };
   }
+  return { timeoutMs: optionsOrTimeout.timeoutMs, env: optionsOrTimeout.env, input: optionsOrTimeout.input };
 }
 
-function runCommand(command: string, promptPayload: Record<string, unknown>, timeoutSeconds: number): Promise<string> {
+function defaultCommandRunner(argv: string[], optionsOrTimeout: number | CommandOptions): Promise<CommandRunResult> {
+  const options = normalizeCommandOptions(optionsOrTimeout);
   return new Promise((resolve, reject) => {
-    const child = spawn(command, {
-      shell: true,
+    if (!Array.isArray(argv) || argv.length === 0 || !argv[0]) {
+      reject(new Error('command argv must include a binary name'));
+      return;
+    }
+
+    const child = spawn(argv[0], argv.slice(1), {
       env: {
         ...process.env,
-        PLASHBOARD_PROMPT_JSON: JSON.stringify(promptPayload)
-      }
+        ...(options.env || {})
+      },
+      stdio: 'pipe'
     });
 
+    const timeoutMs = Math.max(1000, Math.floor(options.timeoutMs));
+    let terminatedByTimeout = false;
     const timer = setTimeout(() => {
+      terminatedByTimeout = true;
       child.kill('SIGKILL');
-      reject(new Error(`fill command timed out after ${timeoutSeconds}s`));
-    }, timeoutSeconds * 1000);
+    }, timeoutMs);
 
     let stdout = '';
     let stderr = '';
@@ -71,7 +110,6 @@ function runCommand(command: string, promptPayload: Record<string, unknown>, tim
     child.stdout.on('data', (chunk) => {
       stdout += String(chunk);
     });
-
     child.stderr.on('data', (chunk) => {
       stderr += String(chunk);
     });
@@ -81,42 +119,195 @@ function runCommand(command: string, promptPayload: Record<string, unknown>, tim
       reject(error);
     });
 
-    child.on('close', (code) => {
+    child.on('close', (code, signal) => {
       clearTimeout(timer);
-      if (code !== 0) {
-        reject(new Error(`fill command failed (code=${code}): ${stderr.trim() || 'no stderr'}`));
-        return;
-      }
-      resolve(stdout.trim());
+      resolve({
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        code,
+        signal,
+        killed: terminatedByTimeout || code === null,
+        termination: terminatedByTimeout ? 'timeout' : signal ? 'signal' : 'exit'
+      });
     });
+
+    if (typeof options.input === 'string') {
+      child.stdin.write(options.input);
+    }
+    child.stdin.end();
   });
 }
 
+function tryParseJson(input: string): unknown | undefined {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return undefined;
+  }
+}
+
+function stripCodeFence(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith('```') || !trimmed.endsWith('```')) return trimmed;
+  const lines = trimmed.split('\n');
+  if (lines.length < 3) return trimmed;
+  return lines.slice(1, -1).join('\n').trim();
+}
+
+function parseJsonCandidate(input: string): unknown | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+
+  const direct = tryParseJson(trimmed);
+  if (direct !== undefined) return direct;
+
+  const unfenced = stripCodeFence(trimmed);
+  if (unfenced !== trimmed) {
+    const parsed = tryParseJson(unfenced);
+    if (parsed !== undefined) return parsed;
+  }
+
+  const start = trimmed.indexOf('{');
+  const end = trimmed.lastIndexOf('}');
+  if (start >= 0 && end > start) {
+    const maybeObject = trimmed.slice(start, end + 1);
+    const parsed = tryParseJson(maybeObject);
+    if (parsed !== undefined) return parsed;
+  }
+
+  return undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function extractFillResponse(value: unknown, depth = 0): FillResponse | null {
+  if (depth > 10) return null;
+
+  if (typeof value === 'string') {
+    const parsed = parseJsonCandidate(value);
+    if (parsed !== undefined) {
+      return extractFillResponse(parsed, depth + 1);
+    }
+    return null;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = extractFillResponse(item, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  const objectValue = asObject(value);
+  if (!objectValue) return null;
+
+  const valuesRecord = asObject(objectValue.values);
+  if (valuesRecord) {
+    return { values: valuesRecord };
+  }
+
+  for (const nested of Object.values(objectValue)) {
+    const found = extractFillResponse(nested, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+
+function parseFillResponse(output: string, source: string): FillResponse {
+  const extracted = extractFillResponse(output);
+  if (!extracted) {
+    throw new Error(`${source} output did not include a valid {"values": ...} JSON object`);
+  }
+  return extracted;
+}
+
+async function runAndReadStdout(
+  commandRunner: CommandRunner,
+  argv: string[],
+  optionsOrTimeout: number | CommandOptions,
+  label: string
+): Promise<string> {
+  const result = await commandRunner(argv, optionsOrTimeout);
+  if (result.code !== 0) {
+    const reason = result.stderr || result.stdout || result.termination || `exit=${String(result.code)}`;
+    throw new Error(`${label} failed: ${reason}`);
+  }
+  return result.stdout.trim();
+}
+
+class MockFillRunner implements FillRunner {
+  async run(context: FillRunContext): Promise<FillResponse> {
+    const values: Record<string, unknown> = {};
+    for (const field of context.template.fields) {
+      values[field.id] = mockValue(field.type, context.currentValues[field.id], field.id);
+    }
+    return { values };
+  }
+}
+
 class CommandFillRunner implements FillRunner {
-  constructor(private readonly config: PlashboardConfig) {}
+  constructor(
+    private readonly config: PlashboardConfig,
+    private readonly commandRunner: CommandRunner
+  ) {}
 
   async run(context: FillRunContext): Promise<FillResponse> {
     if (!this.config.fill_command) {
       throw new Error('fill_provider=command but fill_command is not configured');
     }
 
-    const promptPayload = buildPromptPayload(context);
-    const output = await runCommand(this.config.fill_command, promptPayload, this.config.session_timeout_seconds);
+    const output = await runAndReadStdout(
+      this.commandRunner,
+      ['sh', '-lc', this.config.fill_command],
+      {
+        timeoutMs: this.config.session_timeout_seconds * 1000,
+        env: {
+          PLASHBOARD_PROMPT_JSON: JSON.stringify(buildPromptPayload(context))
+        }
+      },
+      'fill command'
+    );
 
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(output);
-    } catch {
-      throw new Error('fill command returned non-JSON output');
-    }
+    return parseFillResponse(output, 'fill command');
+  }
+}
+
+class OpenClawFillRunner implements FillRunner {
+  constructor(
+    private readonly config: PlashboardConfig,
+    private readonly commandRunner: CommandRunner
+  ) {}
 
-    return parsed as FillResponse;
+  async run(context: FillRunContext): Promise<FillResponse> {
+    const agentId = (this.config.openclaw_fill_agent_id || 'main').trim() || 'main';
+    const timeoutSeconds = Math.max(10, Math.floor(this.config.session_timeout_seconds));
+    const message = buildOpenClawMessage(context);
+
+    const output = await runAndReadStdout(
+      this.commandRunner,
+      ['openclaw', 'agent', '--agent', agentId, '--message', message, '--json', '--timeout', String(timeoutSeconds)],
+      {
+        timeoutMs: (timeoutSeconds + 30) * 1000
+      },
+      'openclaw fill'
+    );
+
+    return parseFillResponse(output, 'openclaw fill');
   }
 }
 
-export function createFillRunner(config: PlashboardConfig): FillRunner {
+export function createFillRunner(config: PlashboardConfig, deps: FillRunnerDeps = {}): FillRunner {
+  const commandRunner = deps.commandRunner || defaultCommandRunner;
   if (config.fill_provider === 'command') {
-    return new CommandFillRunner(config);
+    return new CommandFillRunner(config, commandRunner);
+  }
+  if (config.fill_provider === 'openclaw') {
+    return new OpenClawFillRunner(config, commandRunner);
   }
   return new MockFillRunner();
 }

package/src/plugin.ts

@@ -1,3 +1,6 @@
+import { spawn } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
 import type { DisplayProfile, ToolResponse } from './types.js';
 import { resolveConfig } from './config.js';
 import { PlashboardRuntime } from './runtime.js';
@@ -11,6 +14,32 @@ type UnknownApi = {
     warn?: (...args: unknown[]) => void;
     error?: (...args: unknown[]) => void;
   };
+  runtime?: {
+    config?: {
+      loadConfig?: () => unknown;
+      writeConfigFile?: (nextConfig: unknown) => Promise<void>;
+    };
+    system?: {
+      runCommandWithTimeout?: (
+        argv: string[],
+        optionsOrTimeout: number | {
+          timeoutMs: number;
+          cwd?: string;
+          input?: string;
+          env?: NodeJS.ProcessEnv;
+          windowsVerbatimArguments?: boolean;
+          noOutputTimeoutMs?: number;
+        }
+      ) => Promise<{
+        stdout: string;
+        stderr: string;
+        code: number | null;
+        signal?: NodeJS.Signals | null;
+        killed?: boolean;
+        termination?: string;
+      }>;
+    };
+  };
   config?: unknown;
   pluginConfig?: unknown;
 };
@@ -42,12 +71,417 @@ function asString(value: unknown): string {
   return typeof value === 'string' ? value : '';
 }
 
+function asNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function asErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === 'string' && error.trim()) return error;
+  return 'unknown error';
+}
+
+type SetupParams = {
+  fill_provider?: 'mock' | 'command' | 'openclaw';
+  fill_command?: string;
+  openclaw_fill_agent_id?: string;
+  data_dir?: string;
+  scheduler_tick_seconds?: number;
+  session_timeout_seconds?: number;
+  width_px?: number;
+  height_px?: number;
+  safe_top_px?: number;
+  safe_bottom_px?: number;
+  safe_side_px?: number;
+  layout_safety_margin_px?: number;
+};
+
+type ExposureParams = {
+  local_url?: string;
+  tailscale_https_port?: number;
+  dashboard_output_path?: string;
+};
+
+type CommandExecResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  error?: string;
+};
+
+function normalizeLocalUrl(raw: string | undefined): string {
+  const fallback = 'http://127.0.0.1:18888';
+  if (!raw || !raw.trim()) return fallback;
+  try {
+    const parsed = new URL(raw.trim());
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return fallback;
+    return parsed.toString();
+  } catch {
+    return fallback;
+  }
+}
+
+function normalizePort(raw: number | undefined, fallback: number): number {
+  const value = typeof raw === 'number' && Number.isFinite(raw) ? Math.floor(raw) : fallback;
+  return Math.max(1, Math.min(65535, value));
+}
+
+function runCommand(binary: string, args: string[], timeoutMs: number): Promise<CommandExecResult> {
+  return new Promise((resolve) => {
+    const child = spawn(binary, args, {
+      env: process.env
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    const finish = (result: CommandExecResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      finish({
+        ok: false,
+        stdout,
+        stderr,
+        code: null,
+        error: `timed out after ${Math.floor(timeoutMs / 1000)}s`
+      });
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      finish({
+        ok: false,
+        stdout,
+        stderr,
+        code: null,
+        error: asString((error as { message?: unknown }).message) || 'spawn failed'
+      });
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      finish({
+        ok: code === 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        code
+      });
+    });
+  });
+}
+
+async function buildExposureGuide(resolvedConfig: ReturnType<typeof resolveConfig>, params: ExposureParams = {}) {
+  const localUrl = normalizeLocalUrl(params.local_url);
+  const httpsPort = normalizePort(asNumber(params.tailscale_https_port), 8444);
+  const dashboardPath = (params.dashboard_output_path || resolvedConfig.dashboard_output_path).trim();
+
+  return {
+    ok: true,
+    errors: [],
+    data: {
+      local_url: localUrl,
+      tailscale_https_port: httpsPort,
+      dashboard_output_path: dashboardPath,
+      commands: [
+        `tailscale serve status`,
+        `tailscale serve --https=${httpsPort} ${localUrl}`,
+        `tailscale serve status`,
+        `tailscale serve --https=${httpsPort} off`
+      ],
+      checks: [
+        `test -f ${dashboardPath}`,
+        `curl -I ${localUrl}`
+      ],
+      notes: [
+        'plashboard only writes dashboard JSON; your local UI/server must serve it.',
+        'the tailscale mapping reuses your existing tailnet identity.',
+        'choose a port not already used by another tailscale serve mapping.'
+      ]
+    }
+  } satisfies ToolResponse<Record<string, unknown>>;
+}
+
+async function runExposureCheck(resolvedConfig: ReturnType<typeof resolveConfig>, params: ExposureParams = {}) {
+  const localUrl = normalizeLocalUrl(params.local_url);
+  const httpsPort = normalizePort(asNumber(params.tailscale_https_port), 8444);
+  const dashboardPath = (params.dashboard_output_path || resolvedConfig.dashboard_output_path).trim();
+  const errors: string[] = [];
+
+  let dashboardExists = false;
+  let dashboardSizeBytes: number | undefined;
+  let dashboardMtimeIso: string | undefined;
+
+  try {
+    await access(dashboardPath, fsConstants.R_OK);
+    const info = await stat(dashboardPath);
+    dashboardExists = true;
+    dashboardSizeBytes = info.size;
+    dashboardMtimeIso = info.mtime.toISOString();
+  } catch {
+    errors.push(`dashboard file is not readable: ${dashboardPath}`);
+  }
+
+  let localUrlOk = false;
+  let localStatusCode: number | undefined;
+  let localError: string | undefined;
+
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    const response = await fetch(localUrl, {
+      method: 'GET',
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    localStatusCode = response.status;
+    localUrlOk = response.status >= 200 && response.status < 500;
+    if (!localUrlOk) {
+      errors.push(`local dashboard URL returned status ${response.status}: ${localUrl}`);
+    }
+  } catch (error) {
+    localError = asErrorMessage(error);
+    errors.push(`local dashboard URL is not reachable: ${localUrl} (${localError})`);
+  }
+
+  const tailscale = await runCommand('tailscale', ['serve', 'status'], 8000);
+  const tailscaleOutput = `${tailscale.stdout}\n${tailscale.stderr}`.trim();
+  let tailscalePortConfigured = false;
+
+  if (!tailscale.ok) {
+    errors.push(`tailscale serve status failed: ${tailscale.error || tailscale.stderr || `exit ${tailscale.code}`}`);
+  } else {
+    tailscalePortConfigured = tailscaleOutput.includes(`:${httpsPort}`);
+    if (!tailscalePortConfigured) {
+      errors.push(`tailscale serve has no mapping for https port ${httpsPort}`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    data: {
+      dashboard_output_path: dashboardPath,
+      dashboard_exists: dashboardExists,
+      dashboard_size_bytes: dashboardSizeBytes,
+      dashboard_mtime_utc: dashboardMtimeIso,
+      local_url: localUrl,
+      local_url_ok: localUrlOk,
+      local_status_code: localStatusCode,
+      local_error: localError,
+      tailscale_https_port: httpsPort,
+      tailscale_status_ok: tailscale.ok,
+      tailscale_port_configured: tailscalePortConfigured,
+      tailscale_status_excerpt: tailscaleOutput.slice(0, 1200)
+    }
+  } satisfies ToolResponse<Record<string, unknown>>;
+}
+
+async function runSetup(api: UnknownApi, resolvedConfig: ReturnType<typeof resolveConfig>, params: SetupParams = {}) {
+  const loadConfig = api.runtime?.config?.loadConfig;
+  const writeConfigFile = api.runtime?.config?.writeConfigFile;
+
+  if (!loadConfig || !writeConfigFile) {
+    return {
+      ok: false,
+      errors: ['setup is unavailable: runtime config API is not exposed by this OpenClaw build']
+    } satisfies ToolResponse<Record<string, unknown>>;
+  }
+
+  const rootConfig = asObject(loadConfig());
+  const plugins = asObject(rootConfig.plugins);
+  const entries = asObject(plugins.entries);
+  const currentEntry = asObject(entries.plashboard);
+  const currentPluginConfig = asObject(currentEntry.config);
+
+  const existingDisplay = asObject(currentPluginConfig.display_profile);
+  const displayProfile = {
+    width_px: Math.max(
+      320,
+      Math.floor(asNumber(params.width_px) ?? asNumber(existingDisplay.width_px) ?? resolvedConfig.display_profile.width_px)
+    ),
+    height_px: Math.max(
+      240,
+      Math.floor(asNumber(params.height_px) ?? asNumber(existingDisplay.height_px) ?? resolvedConfig.display_profile.height_px)
+    ),
+    safe_top_px: Math.max(
+      0,
+      Math.floor(asNumber(params.safe_top_px) ?? asNumber(existingDisplay.safe_top_px) ?? resolvedConfig.display_profile.safe_top_px)
+    ),
+    safe_bottom_px: Math.max(
+      0,
+      Math.floor(
+        asNumber(params.safe_bottom_px) ?? asNumber(existingDisplay.safe_bottom_px) ?? resolvedConfig.display_profile.safe_bottom_px
+      )
+    ),
+    safe_side_px: Math.max(
+      0,
+      Math.floor(asNumber(params.safe_side_px) ?? asNumber(existingDisplay.safe_side_px) ?? resolvedConfig.display_profile.safe_side_px)
+    ),
+    layout_safety_margin_px: Math.max(
+      0,
+      Math.floor(
+        asNumber(params.layout_safety_margin_px)
+          ?? asNumber(existingDisplay.layout_safety_margin_px)
+          ?? resolvedConfig.display_profile.layout_safety_margin_px
+      )
+    )
+  };
+
+  const currentProvider = asString(currentPluginConfig.fill_provider);
+  const selectedProvider =
+    params.fill_provider
+    || (currentProvider === 'command' || currentProvider === 'mock' || currentProvider === 'openclaw'
+      ? currentProvider
+      : resolvedConfig.fill_provider);
+  const selectedCommand = (
+    params.fill_command
+    || asString(currentPluginConfig.fill_command)
+    || asString(resolvedConfig.fill_command)
+  ).trim();
+  const selectedAgentId = (
+    params.openclaw_fill_agent_id
+    || asString(currentPluginConfig.openclaw_fill_agent_id)
+    || asString(resolvedConfig.openclaw_fill_agent_id)
+    || 'main'
+  ).trim();
+
+  if (selectedProvider === 'command' && !selectedCommand) {
+    return {
+      ok: false,
+      errors: ['fill_provider=command requires fill_command']
+    } satisfies ToolResponse<Record<string, unknown>>;
+  }
+  if (selectedProvider === 'openclaw' && !selectedAgentId) {
+    return {
+      ok: false,
+      errors: ['fill_provider=openclaw requires openclaw_fill_agent_id']
+    } satisfies ToolResponse<Record<string, unknown>>;
+  }
+
+  const nextPluginConfig: Record<string, unknown> = {
+    ...currentPluginConfig,
+    data_dir: params.data_dir || asString(currentPluginConfig.data_dir) || resolvedConfig.data_dir,
+    scheduler_tick_seconds: Math.max(
+      5,
+      Math.floor(
+        asNumber(params.scheduler_tick_seconds)
+        ?? asNumber(currentPluginConfig.scheduler_tick_seconds)
+        ?? resolvedConfig.scheduler_tick_seconds
+      )
+    ),
+    session_timeout_seconds: Math.max(
+      10,
+      Math.floor(
+        asNumber(params.session_timeout_seconds)
+        ?? asNumber(currentPluginConfig.session_timeout_seconds)
+        ?? resolvedConfig.session_timeout_seconds
+      )
+    ),
+    fill_provider: selectedProvider,
+    display_profile: displayProfile
+  };
+
+  if (selectedCommand) {
+    nextPluginConfig.fill_command = selectedCommand;
+  } else {
+    delete nextPluginConfig.fill_command;
+  }
+  if (selectedProvider === 'openclaw') {
+    nextPluginConfig.openclaw_fill_agent_id = selectedAgentId;
+  } else {
+    delete nextPluginConfig.openclaw_fill_agent_id;
+  }
+
+  const nextRootConfig = {
+    ...rootConfig,
+    plugins: {
+      ...plugins,
+      entries: {
+        ...entries,
+        plashboard: {
+          ...currentEntry,
+          enabled: true,
+          config: nextPluginConfig
+        }
+      }
+    }
+  };
+
+  await writeConfigFile(nextRootConfig);
+
+  return {
+    ok: true,
+    errors: [],
+    data: {
+      configured: true,
+      restart_required: true,
+      plugin_id: 'plashboard',
+      fill_provider: selectedProvider,
+      fill_command: selectedProvider === 'command' ? selectedCommand : undefined,
+      openclaw_fill_agent_id: selectedProvider === 'openclaw' ? selectedAgentId : undefined,
+      data_dir: nextPluginConfig.data_dir,
+      scheduler_tick_seconds: nextPluginConfig.scheduler_tick_seconds,
+      session_timeout_seconds: nextPluginConfig.session_timeout_seconds,
+      display_profile: displayProfile,
+      next_steps: [
+        'restart OpenClaw gateway',
+        'run /plashboard init'
+      ]
+    }
+  } satisfies ToolResponse<Record<string, unknown>>;
+}
+
 export function registerPlashboardPlugin(api: UnknownApi): void {
   const config = resolveConfig(api);
+  const runtimeCommand = api.runtime?.system?.runCommandWithTimeout;
+  const fillCommandRunner = runtimeCommand
+    ? async (
+      argv: string[],
+      optionsOrTimeout: number | {
+        timeoutMs: number;
+        cwd?: string;
+        input?: string;
+        env?: NodeJS.ProcessEnv;
+        windowsVerbatimArguments?: boolean;
+        noOutputTimeoutMs?: number;
+      }
+    ) => {
+      const result = await runtimeCommand(argv, optionsOrTimeout);
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        code: result.code,
+        signal: result.signal,
+        killed: result.killed,
+        termination: result.termination
+      };
+    }
+    : undefined;
   const runtime = new PlashboardRuntime(config, {
     info: (...args) => api.logger?.info?.(...args),
     warn: (...args) => api.logger?.warn?.(...args),
     error: (...args) => api.logger?.error?.(...args)
+  }, {
+    commandRunner: fillCommandRunner
   });
 
   api.registerService?.({
@@ -60,6 +494,66 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
     }
   });
 
+  api.registerTool?.({
+    name: 'plashboard_exposure_guide',
+    description: 'Return copy-paste commands to expose dashboard UI over existing Tailscale.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        local_url: { type: 'string' },
+        tailscale_https_port: { type: 'number' },
+        dashboard_output_path: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: ExposureParams = {}) =>
+      toToolResult(await buildExposureGuide(config, params))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_exposure_check',
+    description: 'Check dashboard file, local URL, and tailscale serve mapping health.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        local_url: { type: 'string' },
+        tailscale_https_port: { type: 'number' },
+        dashboard_output_path: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: ExposureParams = {}) =>
+      toToolResult(await runExposureCheck(config, params))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_setup',
+    description: 'Bootstrap or update plashboard plugin configuration in openclaw.json.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        fill_provider: { type: 'string', enum: ['mock', 'command', 'openclaw'] },
+        fill_command: { type: 'string' },
+        openclaw_fill_agent_id: { type: 'string' },
+        data_dir: { type: 'string' },
+        scheduler_tick_seconds: { type: 'number' },
+        session_timeout_seconds: { type: 'number' },
+        width_px: { type: 'number' },
+        height_px: { type: 'number' },
+        safe_top_px: { type: 'number' },
+        safe_bottom_px: { type: 'number' },
+        safe_side_px: { type: 'number' },
+        layout_safety_margin_px: { type: 'number' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: SetupParams = {}) =>
+      toToolResult(await runSetup(api, config, params))
+  });
+
   api.registerTool?.({
     name: 'plashboard_init',
     description: 'Initialize plashboard state directories and optional default template.',
@@ -240,6 +734,39 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
       const args = asString(ctx.args).split(/\s+/).filter(Boolean);
       const [cmd, ...rest] = args;
 
+      if (cmd === 'expose-guide') {
+        const localUrl = rest.find((token) => token.startsWith('http://') || token.startsWith('https://'));
+        const portToken = rest.find((token) => /^[0-9]+$/.test(token));
+        return toCommandResult(
+          await buildExposureGuide(config, {
+            local_url: localUrl,
+            tailscale_https_port: portToken ? Number(portToken) : undefined
+          })
+        );
+      }
+      if (cmd === 'expose-check') {
+        const localUrl = rest.find((token) => token.startsWith('http://') || token.startsWith('https://'));
+        const portToken = rest.find((token) => /^[0-9]+$/.test(token));
+        return toCommandResult(
+          await runExposureCheck(config, {
+            local_url: localUrl,
+            tailscale_https_port: portToken ? Number(portToken) : undefined
+          })
+        );
+      }
+      if (cmd === 'setup') {
+        const mode = asString(rest[0]).toLowerCase();
+        const fillProvider = mode === 'command' || mode === 'mock' || mode === 'openclaw' ? mode : undefined;
+        const fillCommand = fillProvider === 'command' ? rest.slice(1).join(' ').trim() || undefined : undefined;
+        const fillAgentId = fillProvider === 'openclaw' ? (rest[1] || '').trim() || undefined : undefined;
+        return toCommandResult(
+          await runSetup(api, config, {
+            fill_provider: fillProvider,
+            fill_command: fillCommand,
+            openclaw_fill_agent_id: fillAgentId
+          })
+        );
+      }
       if (cmd === 'init') return toCommandResult(await runtime.init());
       if (cmd === 'status') return toCommandResult(await runtime.status());
       if (cmd === 'list') return toCommandResult(await runtime.templateList());
@@ -264,7 +791,7 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
       return toCommandResult({
         ok: false,
         errors: [
-          'unknown command. supported: init, status, list, activate <id>, delete <id>, copy <src> <new-id> [new-name] [activate], run <id>, set-display <width> <height> <top> <bottom>'
+          'unknown command. supported: setup [openclaw [agent_id]|mock|command <fill_command>], expose-guide [local_url] [https_port], expose-check [local_url] [https_port], init, status, list, activate <id>, delete <id>, copy <src> <new-id> [new-name] [activate], run <id>, set-display <width> <height> <top> <bottom>'
         ]
       });
     }

package/src/runtime.ts

@@ -5,6 +5,7 @@ import type {
   DashboardTemplate,
   DisplayProfile,
   FillResponse,
+  FillRunner,
   PlashboardConfig,
   PlashboardState,
   RunArtifact,
@@ -16,7 +17,7 @@ import { asErrorMessage, atomicWriteJson, deepClone, ensureDir, nowIso, sleep }
 import { collectCurrentValues, mergeTemplateValues, validateFieldPointers } from './merge.js';
 import { validateFillShape, validateTemplateShape } from './schema-validation.js';
 import { DashboardValidatorPublisher } from './publisher.js';
-import { createFillRunner } from './fill-runner.js';
+import { createFillRunner, type FillRunnerDeps } from './fill-runner.js';
 
 interface Logger {
   info(message: string, ...args: unknown[]): void;
@@ -55,7 +56,7 @@ export class PlashboardRuntime {
   private readonly templateStore: TemplateStore;
   private readonly runStore: RunStore;
   private readonly publisher: DashboardValidatorPublisher;
-  private readonly fillRunner;
+  private readonly fillRunner: FillRunner;
 
   private schedulerTimer: NodeJS.Timeout | null = null;
   private tickInProgress = false;
@@ -64,14 +65,15 @@ export class PlashboardRuntime {
 
   constructor(
     private readonly config: PlashboardConfig,
-    private readonly logger: Logger = NOOP_LOGGER
+    private readonly logger: Logger = NOOP_LOGGER,
+    fillRunnerDeps: FillRunnerDeps = {}
   ) {
     this.paths = new Paths(config);
     this.stateStore = new StateStore(this.paths);
     this.templateStore = new TemplateStore(this.paths);
     this.runStore = new RunStore(this.paths);
     this.publisher = new DashboardValidatorPublisher(config);
-    this.fillRunner = createFillRunner(config);
+    this.fillRunner = createFillRunner(config, fillRunnerDeps);
   }
 
   async start(): Promise<void> {

package/src/types.ts

@@ -23,8 +23,9 @@ export interface PlashboardConfig {
   default_retry_count: number;
   retry_backoff_seconds: number;
   session_timeout_seconds: number;
-  fill_provider: 'command' | 'mock';
+  fill_provider: 'command' | 'mock' | 'openclaw';
   fill_command?: string;
+  openclaw_fill_agent_id?: string;
   python_bin: string;
   writer_script_path: string;
   dashboard_output_path: string;