@2en/clawly-plugins 1.4.1 → 1.5.0

package/channel.ts

@@ -9,8 +9,8 @@
 
 import {$} from 'zx'
 import type {PluginApi} from './index'
-import {sendPushNotification} from './notification'
-import {isClientOnline} from './presence'
+import {sendPushNotification} from './gateway/notification'
+import {isClientOnline} from './gateway/presence'
 
 $.verbose = false
 

package/{echo.ts → command/clawly_echo.ts}

@@ -3,7 +3,7 @@
  * invoking the LLM.
  */
 
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 
 export function registerEchoCommand(api: PluginApi) {
   api.registerCommand({

package/command/index.ts

@@ -0,0 +1,6 @@
+import type {PluginApi} from '../index'
+import {registerEchoCommand} from './clawly_echo'
+
+export function registerCommands(api: PluginApi) {
+  registerEchoCommand(api)
+}

package/{agent-send.ts → gateway/agent.ts}

@@ -9,7 +9,7 @@
  */
 
 import {$} from 'zx'
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 import {sendPushNotification} from './notification'
 import {isClientOnline} from './presence'
 

package/gateway/clawhub2gateway.md

@@ -0,0 +1,68 @@
+# clawhub2gateway
+
+OpenClaw plugin that wraps the **ClawHub CLI** as **Gateway WebSocket RPC methods**.
+
+## What you get
+
+Gateway methods (call via WS RPC):
+
+- `clawhub2gateway.search`
+- `clawhub2gateway.explore`
+- `clawhub2gateway.install`
+- `clawhub2gateway.update`
+- `clawhub2gateway.list`
+- `clawhub2gateway.inspect`
+- `clawhub2gateway.star`
+- `clawhub2gateway.unstar`
+
+## Install on a gateway host
+
+1) Install the ClawHub CLI (must be on PATH for the OpenClaw process):
+
+```bash
+npm i -g clawhub
+```
+
+2) Put this plugin on the gateway host and make it discoverable. Common options:
+
+- **Workspace plugin**: copy this folder to `<workspace>/.openclaw/extensions/clawhub2gateway/`
+  with `index.ts` + `openclaw.plugin.json`
+- **Config path**: set `plugins.load.paths` to the plugin folder path
+
+3) Enable the plugin in your `openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "entries": {
+      "clawhub2gateway": { "enabled": true, "config": {} }
+    }
+  }
+}
+```
+
+## Plugin config
+
+Configured under `plugins.entries.clawhub2gateway.config`:
+
+- `bin` (string, default: `"clawhub"`): command to execute
+- `defaultDir` (string, default: `"skills"`): default `--dir`
+- `defaultNoInput` (boolean, default: `true`): default `--no-input`
+- `defaultTimeoutMs` (number, default: `60000`)
+- `configPath` (string, optional): sets `CLAWHUB_CONFIG_PATH`. Defaults to
+  `<OPENCLAW_STATE_DIR>/clawhub/config.json` when state dir is known.
+
+## Call examples (RPC params)
+
+Install:
+
+```json
+{ "method": "clawhub2gateway.install", "params": { "slug": "my-skill-pack" } }
+```
+
+Explore:
+
+```json
+{ "method": "clawhub2gateway.explore", "params": { "limit": 50, "sort": "trending", "json": true } }
+```

package/gateway/clawhub2gateway.ts

@@ -0,0 +1,405 @@
+/**
+ * ClawHub CLI RPC bridge — expose ClawHub CLI commands as Gateway RPC methods.
+ *
+ * Gateway methods:
+ * - clawhub2gateway.search
+ * - clawhub2gateway.install
+ * - clawhub2gateway.update
+ * - clawhub2gateway.list
+ * - clawhub2gateway.explore
+ * - clawhub2gateway.inspect
+ * - clawhub2gateway.star
+ * - clawhub2gateway.unstar
+ *
+ * Notes:
+ * - This plugin shells out to the `clawhub` CLI. Install it on the gateway host:
+ *   `npm i -g clawhub` (or ensure it is in PATH).
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type {PluginApi} from '../index'
+
+type JsonSchema = Record<string, unknown>
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return Boolean(v && typeof v === 'object' && !Array.isArray(v))
+}
+
+function readBool(params: Record<string, unknown>, key: string): boolean | undefined {
+  return typeof params[key] === 'boolean' ? (params[key] as boolean) : undefined
+}
+
+function readString(params: Record<string, unknown>, key: string): string | undefined {
+  const v = params[key]
+  if (typeof v !== 'string') return undefined
+  const t = v.trim()
+  return t ? t : undefined
+}
+
+function readNumber(params: Record<string, unknown>, key: string): number | undefined {
+  const v = params[key]
+  if (typeof v === 'number' && Number.isFinite(v)) return v
+  if (typeof v === 'string' && v.trim()) {
+    const n = Number(v.trim())
+    if (Number.isFinite(n)) return n
+  }
+  return undefined
+}
+
+function coercePluginConfig(api: PluginApi): Record<string, unknown> {
+  return isRecord(api.pluginConfig) ? api.pluginConfig : {}
+}
+
+function configString(
+  cfg: Record<string, unknown>,
+  key: string,
+  fallback?: string,
+): string | undefined {
+  const v = cfg[key]
+  if (typeof v === 'string' && v.trim()) return v.trim()
+  return fallback
+}
+
+function configBool(cfg: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  const v = cfg[key]
+  if (typeof v === 'boolean') return v
+  return fallback
+}
+
+function configNumber(cfg: Record<string, unknown>, key: string, fallback: number): number {
+  const v = cfg[key]
+  if (typeof v === 'number' && Number.isFinite(v)) return v
+  return fallback
+}
+
+async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, {recursive: true})
+}
+
+function buildGlobalCliArgs(
+  params: Record<string, unknown>,
+  defaults: {dir: string; noInput: boolean},
+) {
+  const out: string[] = []
+
+  const workdir = readString(params, 'workdir')
+  const dir = readString(params, 'dir') ?? defaults.dir
+  const site = readString(params, 'site')
+  const registry = readString(params, 'registry')
+  const noInput = readBool(params, 'noInput') ?? defaults.noInput
+
+  if (workdir) out.push('--workdir', workdir)
+  if (dir) out.push('--dir', dir)
+  if (site) out.push('--site', site)
+  if (registry) out.push('--registry', registry)
+  if (noInput) out.push('--no-input')
+
+  return out
+}
+
+async function runClawhubCommand(opts: {
+  api: PluginApi
+  argv: string[]
+  cwd?: string
+  timeoutMs: number
+  env?: Record<string, string | undefined>
+}) {
+  const runner = opts.api.runtime.system?.runCommandWithTimeout
+  if (!runner) {
+    throw new Error('Plugin runtime missing system.runCommandWithTimeout')
+  }
+  const result = await runner(opts.argv, {timeoutMs: opts.timeoutMs, cwd: opts.cwd, env: opts.env})
+  return result
+}
+
+function joinOutput(stdout: string, stderr: string): string {
+  const s1 = (stdout ?? '').trimEnd()
+  const s2 = (stderr ?? '').trimEnd()
+  if (s1 && s2) return `${s1}\n\n${s2}`
+  return s1 || s2 || ''
+}
+
+function baseToolParamsSchema(extra?: JsonSchema): JsonSchema {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      workdir: {type: 'string', description: 'Working directory (ClawHub --workdir)'},
+      dir: {type: 'string', description: 'Skills directory relative to workdir (ClawHub --dir)'},
+      site: {type: 'string', description: 'ClawHub site URL (ClawHub --site)'},
+      registry: {type: 'string', description: 'ClawHub registry API URL (ClawHub --registry)'},
+      noInput: {type: 'boolean', description: 'Disable prompts (ClawHub --no-input)'},
+      timeoutMs: {type: 'number', description: 'Command timeout in milliseconds'},
+      ...(extra ?? {}),
+    },
+  }
+}
+
+export function registerClawhub2gateway(api: PluginApi) {
+  const cfg = coercePluginConfig(api)
+  const bin = configString(cfg, 'bin', 'clawhub') ?? 'clawhub'
+  const defaultDir = configString(cfg, 'defaultDir', 'skills') ?? 'skills'
+  const defaultNoInput = configBool(cfg, 'defaultNoInput', true)
+  const defaultTimeoutMs = configNumber(cfg, 'defaultTimeoutMs', 60_000)
+  const configPath = configString(cfg, 'configPath')
+
+  const stateDir =
+    api.runtime.state?.resolveStateDir?.(process.env) ??
+    process.env.OPENCLAW_STATE_DIR ??
+    process.env.CLAWDBOT_STATE_DIR ??
+    ''
+  const defaultConfigPath = stateDir ? path.join(stateDir, 'clawhub', 'config.json') : ''
+
+  const resolveEnv = async (): Promise<Record<string, string | undefined>> => {
+    const env: Record<string, string | undefined> = {}
+    const resolved = configPath ?? defaultConfigPath
+    if (resolved) {
+      await ensureDir(path.dirname(resolved))
+      env.CLAWHUB_CONFIG_PATH = resolved
+    }
+    return env
+  }
+
+  const registerRpc = (rpc: {
+    method: string
+    description: string
+    parameters: JsonSchema
+    buildCli: (
+      params: Record<string, unknown>,
+    ) => Promise<{argv: string[]; cwd?: string; timeoutMs?: number}>
+  }) => {
+    api.registerGatewayMethod(rpc.method, async ({params, respond}) => {
+      try {
+        const timeoutMs = Math.max(
+          1_000,
+          Math.floor(readNumber(params, 'timeoutMs') ?? defaultTimeoutMs),
+        )
+        const built = await rpc.buildCli(params)
+        const env = await resolveEnv()
+        const res = await runClawhubCommand({
+          api,
+          argv: built.argv,
+          cwd: built.cwd,
+          timeoutMs: built.timeoutMs ?? timeoutMs,
+          env,
+        })
+        const output = joinOutput(res.stdout, res.stderr)
+        if (res.code && res.code !== 0) {
+          respond(false, undefined, {
+            code: 'command_failed',
+            message: output || `clawhub exited with code ${res.code}`,
+          })
+          return
+        }
+        respond(true, {
+          ok: true,
+          output,
+          stdout: res.stdout,
+          stderr: res.stderr,
+          code: res.code,
+          signal: res.signal,
+          killed: res.killed,
+          argv: built.argv,
+          cwd: built.cwd,
+        })
+      } catch (err) {
+        respond(false, undefined, {
+          code: 'error',
+          message: err instanceof Error ? err.message : String(err),
+        })
+      }
+    })
+  }
+
+  // -----------------------------
+  // Search
+  // -----------------------------
+
+  registerRpc({
+    method: 'clawhub2gateway.search',
+    description: 'ClawHub CLI: search skills.',
+    parameters: baseToolParamsSchema({
+      query: {type: 'string', description: 'Search query'},
+      limit: {type: 'number', description: 'Max results (clawhub search --limit)'},
+    }),
+    async buildCli(params) {
+      const query = readString(params, 'query')
+      if (!query) throw new Error('query required')
+      const limit = readNumber(params, 'limit')
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+      const argv = [bin, 'search', query, ...globalArgs]
+      if (limit !== undefined) argv.push('--limit', String(Math.max(1, Math.floor(limit))))
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.explore',
+    description: 'ClawHub CLI: explore skills.!',
+    parameters: baseToolParamsSchema({
+      limit: {type: 'number', description: 'Max results (clawhub explore --limit, if supported)'},
+      sort: {
+        type: 'string',
+        enum: ['newest', 'downloads', 'rating', 'installs', 'installsAllTime', 'trending'],
+        description:
+          'Sort order (clawhub explore --sort). One of newest, downloads, rating, installs, installsAllTime, trending.',
+      },
+      json: {type: 'boolean', description: 'Output JSON'},
+    }),
+    async buildCli(params) {
+      const limit = readNumber(params, 'limit')
+      const sort = readString(params, 'sort')
+      const json = readBool(params, 'json') ?? false
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+      const argv = [bin, 'explore', ...globalArgs]
+      if (limit !== undefined) argv.push('--limit', String(Math.max(1, Math.floor(limit))))
+      if (sort) argv.push('--sort', sort)
+      if (json) argv.push('--json')
+      return {argv}
+    },
+  })
+
+  // -----------------------------
+  // Install / Update / List
+  // -----------------------------
+
+  registerRpc({
+    method: 'clawhub2gateway.install',
+    description: 'ClawHub CLI: install a skill into the workspace skills dir.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug to install'},
+      version: {type: 'string', description: 'Specific version to install'},
+      force: {
+        type: 'boolean',
+        description: 'Overwrite if folder exists (clawhub install --force)',
+      },
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const version = readString(params, 'version')
+      const force = readBool(params, 'force') ?? false
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+      const argv = [bin, 'install', slug, ...globalArgs]
+      if (version) argv.push('--version', version)
+      if (force) argv.push('--force')
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.update',
+    description: 'ClawHub CLI: update one skill or all installed skills.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug to update (omit when all=true)'},
+      all: {type: 'boolean', description: 'Update all skills (clawhub update --all)'},
+      version: {type: 'string', description: 'Update to a specific version (single slug only)'},
+      force: {
+        type: 'boolean',
+        description: 'Overwrite when local files do not match any published version',
+      },
+    }),
+    async buildCli(params) {
+      const all = readBool(params, 'all') ?? false
+      const slug = readString(params, 'slug')
+      const version = readString(params, 'version')
+      const force = readBool(params, 'force') ?? false
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+
+      const argv = [bin, 'update', ...globalArgs]
+      if (all) {
+        argv.push('--all')
+      } else {
+        if (!slug) throw new Error('slug required when all=false')
+        argv.push(slug)
+        if (version) argv.push('--version', version)
+      }
+      if (force) argv.push('--force')
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.list',
+    description: 'ClawHub CLI: list installed skills from .clawhub/lock.json.',
+    parameters: baseToolParamsSchema(),
+    async buildCli(params) {
+      const argv = [
+        bin,
+        'list',
+        ...buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput}),
+      ]
+      return {argv}
+    },
+  })
+
+  // -----------------------------
+  // Inspect / Star
+  // -----------------------------
+
+  registerRpc({
+    method: 'clawhub2gateway.inspect',
+    description: 'ClawHub CLI: inspect a skill without installing.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug'},
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const globalArgs = buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput})
+
+      const argv = [bin, 'inspect', slug, ...globalArgs]
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.star',
+    description: 'ClawHub CLI: star a skill.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug'},
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const argv = [
+        bin,
+        'star',
+        slug,
+        ...buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput}),
+      ]
+      return {argv}
+    },
+  })
+
+  registerRpc({
+    method: 'clawhub2gateway.unstar',
+    description: 'ClawHub CLI: unstar a skill.',
+    parameters: baseToolParamsSchema({
+      slug: {type: 'string', description: 'Skill slug'},
+    }),
+    async buildCli(params) {
+      const slug = readString(params, 'slug')
+      if (!slug) throw new Error('slug required')
+      const argv = [
+        bin,
+        'unstar',
+        slug,
+        ...buildGlobalCliArgs(params, {dir: defaultDir, noInput: defaultNoInput}),
+      ]
+      return {argv}
+    },
+  })
+
+  api.logger.info(
+    [
+      `clawhub2gateway: registered.`,
+      `Using clawhub bin: ${bin}`,
+      defaultConfigPath
+        ? `CLI config: ${configPath ?? defaultConfigPath}`
+        : 'CLI config: (not set)',
+    ].join(' '),
+  )
+}

package/gateway/index.ts

@@ -0,0 +1,14 @@
+import type {PluginApi} from '../index'
+import {registerAgentSend} from './agent'
+import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerMemoryBrowser} from './memory'
+import {registerNotification} from './notification'
+import {registerPresence} from './presence'
+
+export function registerGateway(api: PluginApi) {
+  registerPresence(api)
+  registerNotification(api)
+  registerAgentSend(api)
+  registerMemoryBrowser(api)
+  registerClawhub2gateway(api)
+}

package/gateway/memory-browser.md

@@ -0,0 +1,55 @@
+# memory-browser
+
+OpenClaw plugin that exposes the **memory directory** (all `.md` files) as **Gateway WebSocket RPC methods**.
+
+## What you get
+
+Gateway methods (call via WS RPC):
+
+- **`memory-browser.list`** — List all `.md` files in the memory directory (recursive). Returns `{ files: string[] }` (relative paths).
+- **`memory-browser.get`** — Return the content of a single `.md` file. Params: `{ path: string }` (relative path, e.g. `"notes/foo.md"`). Returns `{ path: string, content: string }`.
+
+## Memory directory
+
+The memory directory is resolved in this order:
+
+1. Plugin config `memoryDir` (absolute path)
+2. `<OPENCLAW_STATE_DIR>/memory` (or `<CLAWDBOT_STATE_DIR>/memory`)
+3. `<process.cwd()>/memory`
+
+## Install on a gateway host
+
+1. Put this plugin on the gateway host and make it discoverable, e.g.:
+   - Workspace: `<workspace>/.openclaw/extensions/memory-browser/` with `index.ts` + `openclaw.plugin.json`
+   - Or set `plugins.load.paths` to the plugin folder
+
+2. Enable the plugin in `openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "enabled": true,
+    "entries": {
+      "memory-browser": { "enabled": true, "config": {} }
+    }
+  }
+}
+```
+
+Optional config: `config.memoryDir` to override the memory directory path.
+
+## Call examples (RPC params)
+
+List all `.md` files:
+
+```json
+{ "method": "memory-browser.list", "params": {} }
+```
+
+Get one file:
+
+```json
+{ "method": "memory-browser.get", "params": { "path": "notes/meeting-2024.md" } }
+```
+
+`path` must be a relative path to a `.md` file inside the memory directory; directory traversal (`..`) is rejected.

package/gateway/memory.ts

@@ -0,0 +1,187 @@
+/**
+ * Memory directory browser — expose memory directory .md files as Gateway RPC methods.
+ *
+ * Gateway methods:
+ * - memory-browser.list — list all .md files in the OpenClaw memory directory
+ * - memory-browser.get — return the content of a single .md file by path
+ */
+
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import type {PluginApi} from '../index'
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return Boolean(v && typeof v === 'object' && !Array.isArray(v))
+}
+
+function configString(
+  cfg: Record<string, unknown>,
+  key: string,
+  fallback?: string,
+): string | undefined {
+  const v = cfg[key]
+  if (typeof v === 'string' && v.trim()) return v.trim()
+  return fallback
+}
+
+function readString(params: Record<string, unknown>, key: string): string | undefined {
+  const v = params[key]
+  if (typeof v !== 'string') return undefined
+  const t = v.trim()
+  return t ? t : undefined
+}
+
+function coercePluginConfig(api: PluginApi): Record<string, unknown> {
+  return isRecord(api.pluginConfig) ? api.pluginConfig : {}
+}
+
+/** Resolve the memory directory path. Memory lives under workspace (agents.defaults.workspace). */
+function resolveMemoryDir(api: PluginApi, profile?: string): string {
+  const cfg = coercePluginConfig(api)
+  const configPath = configString(cfg, 'memoryDir')
+  if (configPath) return configPath
+
+  const baseDir =
+    process.env.OPENCLAW_WORKSPACE ?? path.join(os.homedir(), '.openclaw', 'workspace')
+  // Profile-aware: "main" or empty → default workspace, otherwise workspace-<profile>
+  if (profile && profile !== 'main') {
+    const parentDir = path.dirname(baseDir)
+    const baseName = path.basename(baseDir)
+    return path.join(parentDir, `${baseName}-${profile}`, 'memory')
+  }
+  return path.join(baseDir, 'memory')
+}
+
+/** Check that a relative path is safe (no directory traversal). */
+function isSafeRelativePath(relativePath: string): boolean {
+  if (!relativePath || relativePath.startsWith('/') || relativePath.includes('\\')) {
+    return false
+  }
+  const normalized = path.normalize(relativePath)
+  if (normalized.startsWith('..') || normalized.includes('..')) {
+    return false
+  }
+  return true
+}
+
+/** Recursively collect all .md file paths under dir, relative to baseDir. */
+async function collectMdFiles(dir: string, baseDir: string, acc: string[] = []): Promise<string[]> {
+  let entries: fs.Dirent[]
+  try {
+    entries = await fs.readdir(dir, {withFileTypes: true})
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return acc
+    throw err
+  }
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name)
+    const rel = path.relative(baseDir, full)
+
+    if (e.isDirectory()) {
+      await collectMdFiles(full, baseDir, acc)
+    } else if (e.isFile() && e.name.toLowerCase().endsWith('.md')) {
+      acc.push(rel)
+    }
+  }
+  return acc
+}
+
+export function registerMemoryBrowser(api: PluginApi) {
+  const memoryDir = resolveMemoryDir(api)
+  api.logger.info(`memory-browser: memory directory: ${memoryDir}`)
+
+  // -----------------------------
+  // memory-browser.list
+  // -----------------------------
+  api.registerGatewayMethod('memory-browser.list', async ({params, respond}) => {
+    try {
+      const profile = readString(params, 'profile')
+      const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
+      const files = await collectMdFiles(dir, dir)
+      api.logger.info(`memory-browser.list: ${files.length} files found`)
+      files.sort()
+      respond(true, {files})
+    } catch (err) {
+      api.logger.error(
+        `memory-browser.list failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  // -----------------------------
+  // memory-browser.get
+  // -----------------------------
+  api.registerGatewayMethod('memory-browser.get', async ({params, respond}) => {
+    const relativePath = readString(params, 'path')
+    const profile = readString(params, 'profile')
+    const dir = profile ? resolveMemoryDir(api, profile) : memoryDir
+    if (!relativePath) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'path (relative path to .md file) is required',
+      })
+      return
+    }
+    if (!isSafeRelativePath(relativePath)) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'path must be a safe relative path (no directory traversal)',
+      })
+      return
+    }
+    if (!relativePath.toLowerCase().endsWith('.md')) {
+      respond(false, undefined, {
+        code: 'invalid_params',
+        message: 'path must point to a .md file',
+      })
+      return
+    }
+
+    const fullPath = path.join(dir, path.normalize(relativePath))
+    const realMemory = await fs.realpath(dir).catch(() => dir)
+    const realResolved = await fs.realpath(fullPath).catch(() => null)
+
+    if (!realResolved) {
+      respond(false, undefined, {
+        code: 'not_found',
+        message: 'file not found',
+      })
+      return
+    }
+    const rel = path.relative(realMemory, realResolved)
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      respond(false, undefined, {
+        code: 'not_found',
+        message: 'file not found or outside memory directory',
+      })
+      return
+    }
+
+    try {
+      const content = await fs.readFile(fullPath, 'utf-8')
+      respond(true, {path: relativePath, content})
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        respond(false, undefined, {code: 'not_found', message: 'file not found'})
+        return
+      }
+      api.logger.error(
+        `memory-browser.get failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.logger.info(`memory-browser: registered (dir: ${memoryDir})`)
+}

package/{notification.ts → gateway/notification.ts}

@@ -13,7 +13,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 
 const TOKEN_DIR = path.join(os.homedir(), '.openclaw', 'clawly')
 const TOKEN_FILE = path.join(TOKEN_DIR, 'expo-push-token.json')

package/{presence.ts → gateway/presence.ts}

@@ -7,7 +7,7 @@
 
 import {$} from 'zx'
 
-import type {PluginApi} from './index'
+import type {PluginApi} from '../index'
 
 $.verbose = false
 

package/index.ts

@@ -1,5 +1,5 @@
 /**
- * OpenClaw plugin: Clawly utility RPC methods (clawly.*).
+ * OpenClaw plugin: Clawly utility RPC methods (clawly.*), memory browser, and ClawHub CLI bridge.
  *
  * Gateway methods:
  * - clawly.file.getOutbound — read a persisted outbound file by original-path hash
@@ -8,6 +8,9 @@
  * - clawly.notification.send    — send a push notification directly
  * - clawly.agent.send        — send a message to the agent (+ optional push)
  * - clawly.agent.echo        — echo-wrapped agent message (bypasses LLM)
+ * - memory-browser.list      — list all .md files in the memory directory
+ * - memory-browser.get       — return content of a single .md file
+ * - clawhub2gateway.*        — ClawHub CLI RPC bridge (search/install/update/list/explore/inspect/star/unstar)
  *
  * Agent tools:
  * - clawly_is_user_online    — check if user's device is connected
@@ -21,19 +24,29 @@
  * - before_tool_call      — enforces delivery fields on cron.create
  */
 
-import {registerAgentSend} from './agent-send'
 import {registerCalendar} from './calendar'
-import {registerIsUserOnlineTool, registerSendAppPushTool} from './tools'
 import {registerClawlyCronChannel} from './channel'
+import {registerCommands} from './command'
 import {registerCronHook} from './cron-hook'
-import {registerEchoCommand} from './echo'
 import {registerEmail} from './email'
+import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
-import {registerNotification} from './notification'
 import {registerOutboundHook, registerOutboundMethods} from './outbound'
-import {registerPresence} from './presence'
+import {registerTools} from './tools'
 
 type PluginRuntime = {
+  system?: {
+    runCommandWithTimeout?: (
+      argv: string[],
+      opts: {timeoutMs: number; cwd?: string; env?: Record<string, string | undefined>},
+    ) => Promise<{
+      stdout: string
+      stderr: string
+      code: number | null
+      signal: string | null
+      killed: boolean
+    }>
+  }
   state?: {
     resolveStateDir?: (env?: NodeJS.ProcessEnv) => string
   }
@@ -86,14 +99,11 @@ export default {
   register(api: PluginApi) {
     registerOutboundHook(api)
     registerOutboundMethods(api)
-    registerEchoCommand(api)
-    registerPresence(api)
-    registerNotification(api)
-    registerAgentSend(api)
-    registerIsUserOnlineTool(api)
-    registerSendAppPushTool(api)
+    registerCommands(api)
+    registerTools(api)
     registerClawlyCronChannel(api)
     registerCronHook(api)
+    registerGateway(api)
 
     // Email & calendar (optional — requires gatewayBaseUrl + gatewayToken in config)
     const gw = getGatewayConfig(api)

package/openclaw.plugin.json

@@ -1,12 +1,51 @@
 {
   "id": "clawly-plugins",
   "name": "Clawly Plugins",
-  "description": "Clawly utility RPC methods (clawly.*): file access, presence, push notifications, and agent messaging.",
+  "description": "Clawly utility RPC methods (clawly.*): file access, presence, push notifications, agent messaging, memory browser, and ClawHub CLI bridge.",
   "version": "0.2.0",
+  "uiHints": {
+    "memoryDir": {
+      "label": "Memory directory",
+      "help": "Absolute path to the memory directory containing .md files. Defaults to <OPENCLAW_WORKSPACE>/memory.",
+      "placeholder": "/data/memory"
+    },
+    "bin": {
+      "label": "clawhub binary",
+      "help": "Command to run (must be in PATH on the gateway host).",
+      "placeholder": "clawhub"
+    },
+    "defaultDir": {
+      "label": "Default skills dir",
+      "help": "Maps to `clawhub --dir` when not provided per-call.",
+      "placeholder": "skills"
+    },
+    "defaultNoInput": {
+      "label": "Default no-input",
+      "help": "If true, adds `--no-input` unless the tool call overrides it.",
+      "advanced": true
+    },
+    "defaultTimeoutMs": {
+      "label": "Default timeout (ms)",
+      "help": "Default command timeout for most tool calls.",
+      "advanced": true
+    },
+    "configPath": {
+      "label": "CLAWHUB_CONFIG_PATH",
+      "help": "Where the ClawHub CLI stores auth/config. Defaults to `<OPENCLAW_STATE_DIR>/clawhub/config.json`.",
+      "advanced": true,
+      "placeholder": "~/.openclaw/clawhub/config.json"
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
+      "memoryDir": { "type": "string", "minLength": 1 },
+      "bin": { "type": "string", "minLength": 1 },
+      "defaultDir": { "type": "string", "minLength": 1 },
+      "defaultNoInput": { "type": "boolean" },
+      "defaultTimeoutMs": { "type": "number", "minimum": 1000 },
+      "configPath": { "type": "string" },
       "gatewayBaseUrl": { "type": "string" },
       "gatewayToken": { "type": "string" }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -12,6 +12,8 @@
     "zx": "npm:zx@8.8.5-lite"
   },
   "files": [
+    "command",
+    "gateway",
     "tools",
     "index.ts",
     "calendar.ts",
@@ -20,11 +22,6 @@
     "email.ts",
     "gateway-fetch.ts",
     "outbound.ts",
-    "echo.ts",
-    "presence.ts",
-    "notification.ts",
-    "agent-send.ts",
-    "tools.ts",
     "openclaw.plugin.json"
   ],
   "publishConfig": {

package/tools/clawly-is-user-online.ts

@@ -5,7 +5,7 @@
  */
 
 import type {PluginApi} from '../index'
-import {isClientOnline} from '../presence'
+import {isClientOnline} from '../gateway/presence'
 
 const TOOL_NAME = 'clawly_is_user_online'
 

package/tools/clawly-send-app-push.ts

@@ -7,7 +7,7 @@
  */
 
 import type {PluginApi} from '../index'
-import {sendPushNotification} from '../notification'
+import {sendPushNotification} from '../gateway/notification'
 
 const TOOL_NAME = 'clawly_send_app_push'
 

package/tools/index.ts

@@ -0,0 +1,8 @@
+import type {PluginApi} from '../index'
+import {registerIsUserOnlineTool} from './clawly-is-user-online'
+import {registerSendAppPushTool} from './clawly-send-app-push'
+
+export function registerTools(api: PluginApi) {
+  registerIsUserOnlineTool(api)
+  registerSendAppPushTool(api)
+}

package/tools.ts

@@ -1,2 +0,0 @@
-export {registerIsUserOnlineTool} from './tools/clawly-is-user-online'
-export {registerSendAppPushTool} from './tools/clawly-send-app-push'