# Ecosystem — Plugins + Hooks + Skills Registry + Cron

## Architecture

```mermaid
flowchart TD
    subgraph ECO["GoClaw Ecosystem Architecture"]
        SDK["<b>Plugin SDK</b><br/>Go interface · Manifest · HTTP routes"]
        HOOKS["<b>Hook Registry</b><br/>12 events · Priority-based · Plugin hooks"]
        SKILLS["<b>Skills Registry</b><br/>Bundled set · Security scan"]
        GW["<b>Gateway (internal/gateway/)</b><br/>plugins.go (discovery + SDK) · hooks.go (registry + emit)"]
        CRON["<b>Cron System (internal/agent/tool_cron.go)</b><br/>LLM-powered scheduling · Persistent, disk-backed"]

        SDK --> GW
        HOOKS --> GW
        SKILLS --> GW
        GW --- CRON
    end
```

---

## Go / OpenClaw Extensions (Section 12)

GoClaw defines a Go plugin SDK and discovers extension manifests. These
extensions are not the [Agent Plugins](#agent-plugins) installed on the Plugins
page. Discovery is all that happens today: manifests found in
`<state dir>/extensions/` and `<workspace>/extensions/` are listed at
`/api/extensions` (the Web UI's System page). No extension code is loaded:
nothing calls `PluginRegistry.Register`, so no extension registers hooks or
HTTP routes, and the `ChannelAdapter` type is not connected to the channels.

| # | Feature | OpenClaw | GoClaw | Status |
|---|---------|----------|---------|--------|
| 12.1 | Plugin discovery and loading | npm packages | Scans `~/.goclaw/extensions/` + workspace, reads `plugin.json` / `openclaw.plugin.json`, lists them at `/api/extensions`; loads nothing | Partial (discovery only) |
| 12.2 | Plugin SDK (interface-based) | JS class | Go `Plugin`, `PluginAPI`, `ChannelAdapter` interfaces, defined but not called | Partial |
| 12.3 | Plugin HTTP routes | ✅ | `RegisterHTTPRoute()` → `/plugins/<id>/...`, method-checked, behind the gateway token | Partial (no extension is loaded to register one) |
| 12.4 | Plugin hook registration | ✅ | `RegisterHook()` → priority-based event handlers | Partial (no extension is loaded to register one) |
| 12.5 | Channel plugin type | ✅ | `ChannelAdapter` interface: `ID()`, `Start()`, `Stop()`, `SendMessage()`, `OnMessage()`; not wired to the channel system | **TODO** |
| 12.6 | Provider plugin type | ✅ | — | **TODO** |
| 12.7 | Tool plugin type | ✅ | — | **TODO** |
| 12.8 | Subprocess plugin runner | JSON-RPC over stdio | — | **TODO** |
| 12.9 | Remote plugin install | npm registry | Agent Plugins from a GitHub repository, an https archive or a marketplace, with update checks (see [Agent Plugins](#agent-plugins)) | Done |

### Plugin SDK

```go
type Plugin interface {
    ID() string
    Register(api PluginAPI) error
    Close() error
}

type PluginAPI interface {
    RegisterHook(event HookEvent, name string, priority int, handler HookHandler)
    RegisterHTTPRoute(method, pattern string, handler http.HandlerFunc)
}

type ChannelAdapter interface {
    ID() string
    Start(ctx context.Context) error
    Stop() error
    SendMessage(peerID, content string) error
    OnMessage(handler func(ctx context.Context, channel, accountID, peerID, content string) (string, error))
}
```

### Plugin Manifest (OpenClaw-compatible)

```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "kind": "channel",
  "channels": ["telegram"],
  "skills": ["telegram-tips"]
}
```

---

## Agent Plugins

An Agent Plugin bundles subagents, instructions, skills, hooks and MCP servers,
in the Agent Plugins layout VS Code and Copilot use (`plugin.json`,
`skills/<name>/SKILL.md`, `mcp.json`), with GoClaw's own parts under
`mn.ulab.goclaw/` (`agents/*.agent.md`, `instructions/*.instructions.md`,
`hooks.json`). The design is in [Tools Engine](tools_engine.md#agent-plugins).

| Feature | GoClaw | Status |
|---------|--------|--------|
| Install | On the Plugins page: from a zip, a GitHub repository, an https archive (sha256 pinnable) or a marketplace (Claude Code's `marketplace.json`, listed under `plugin_marketplaces:`). Installed into `<state dir>/plugins`; nothing is copied into a workspace | Done |
| Per agent | `plugins:` in `config.yaml` names the agents each plugin is on for | Done |
| Override | A workspace file of the same name wins over a plugin's part ("save a copy") | Done |
| Hooks and MCP servers | Off until an admin approves each one; a changed item is off again until re-approved | Done |
| Inputs | `${input:NAME}` in a hook or server is filled from the vault; a plugin carries no secrets | Done |
| Update check | Compares the installed plugin with its source; never installs by itself | Done |
| Export | An agent's own subagents, instructions, skills, hooks and MCP servers as a plugin zip | Done |

---

## Hooks System (Section 18)

GoClaw has two kinds of hooks:

- **Admin hooks** — rules an admin attaches to the agent's tool calls on the
  Hooks page, saved under `hooks:` in `config.yaml` (`/api/hooks/rules`). They
  run around every tool call, in both agent loops, SOP and cron runs and
  subagents. Actions: `block` (before the call), `notify` (a message to a
  channel) and `webhook` (a POST of the call as JSON, signed with
  `X-GoClaw-Signature` when the rule has a secret). A hook that decides fails
  closed: only an explicit `{"decision": "allow"}` lets the call through, and
  an error, timeout or unclear answer blocks it. Agent Plugins can bring hooks
  too, each off until approved. See
  [Tools Engine](tools_engine.md#admin-hooks-rules-on-tool-calls).
- **Gateway events** — `internal/gateway/hooks.go`, a priority-based event
  registry. Handlers registered by Go code observe these events; they cannot
  change or stop what happens.

The table below is about the gateway events, apart from 18.6.

| # | Feature | OpenClaw | GoClaw | Status |
|---|---------|----------|---------|--------|
| 18.1 | Internal hooks (events) | 26 events | **12 events** (see table below) | Done |
| 18.2 | Priority dispatch | No | **Yes** — higher priority handlers fire first | **GoClaw only** |
| 18.3 | Built-in hooks | session-memory, bootstrap-extra-files, command-logger | log-received, log-sent, log-start, log-stop | Done |
| 18.4 | Plugin hook registration | Yes (via SDK) | `PluginAPI.RegisterHook()` exists, but no extension is loaded to call it | Partial |
| 18.5 | Hook listing API | — | ✅ `HookRegistry.List()` → `/api/hooks`, shown in the Hooks card of the Web UI's System page | **GoClaw only** |
| 18.6 | HTTP hooks (webhook triggers) | ✅ | Admin hooks' `webhook` action on tool calls; inbound webhooks at `/goclaw/hook/<type>` run an agent or a SOP | Done |
| 18.7 | Workspace hooks | `~/.openclaw/hooks/` | — | **TODO** |

### Hook Events (12)

| Event | Description |
|-------|-------------|
| `gateway:start` | Gateway starts |
| `gateway:stop` | Gateway shuts down |
| `message:received` | Incoming message from any channel |
| `message:sending` | Before sending response |
| `message:sent` | After response sent |
| `before_tool_call` | Before tool execution |
| `after_tool_call` | After tool execution |
| `session:start` | New session created |
| `session:end` | Session ended |
| `before_prompt_build` | Before system prompt construction |
| `llm:input` | Final prompt sent to LLM |
| `llm:output` | Raw LLM response received |

---

## Skills Registry

`skills-registry/` — curated skills kept in the repository. They are installed
by path, in a checkout of the repository (`goclaw skills install
./skills-registry/gitlab/`), or from a URL or GitHub repository like any other
skill.

There is no install by name. `goclaw skills install registry:<name>`,
`skills search` and `skills registry` were removed: they read a default
registry that was never published, under a GitHub organization GoClaw does not
own.

| # | Feature | OpenClaw | GoClaw | Status |
|---|---------|----------|---------|--------|
| R.1 | Install by name from a registry | npm packages | — (removed; install by path, URL or `github:`) | — |
| R.2 | Skill security scan on install | — | Prompt injection + code pattern detection, critical findings block install | **GoClaw only** |
| R.3 | Manual scan | — | `goclaw skills scan` / `goclaw skills scan <name>` | Done |

### Registry Skills

The skills that ship in `skills-registry/`:

| Skill | Tags | Description |
|-------|------|-------------|
| `server-health` | server, monitoring, admin, devops | Server health monitoring and alerting |
| `gitlab` | gitlab, devops, ci-cd, issues, merge-requests | GitLab project management — issues, MRs, pipelines, CI/CD logs, code search |
| `code-review` | code-review, gitlab, ast, linter, security | Reviews GitLab MRs with AST analysis and linters, and implements coding tasks from issues |
| `sonarqube` | sonarqube, code-quality, security, quality-gate | SonarQube Quality Gate status, issues, code smells, vulnerabilities, security hotspots, metrics |
| `database-analyzer` | database, schema, sql, postgres, mysql, clickhouse, mongodb | Discovers a database's tables, relationships and data dictionary; results cached in memory scope `db_cache`, enrichment notes in `agent_notes` |
| `dependency-mapping` | architecture, dependency, microservice, sre | Finds a codebase's external dependencies (HTTP, gRPC, databases, caches, queues) and maps the system |
| `tcpdump-analyzer` | network, security, pcap, tcpdump, tshark | Packet capture file analysis from a DevOps and security perspective |
| `netbox-infra-manager` | netbox, ipam, dcim, infrastructure, networking | NetBox IPAM/DCIM: register IP addresses, track racks and servers, define VLANs, register virtual machines |

## Cron System (V2)

`internal/agent/cron_scheduler.go` — Persistent job scheduling integrated with the SQLite Job Queue.

| # | Feature | Description | Status |
|---|---------|-------------|--------|
| C.1 | **SQLite Persistence** | Jobs are stored in the `cron_jobs` table, surviving restarts and ensuring data integrity. | Done |
| C.2 | **Job Queue Integration** | Cron tasks (particularly SOPs) trigger entries in the persistent Job Queue for reliable background execution. | Done |
| C.3 | **System Maintenance Jobs** | Automatic system jobs (e.g., `sys-memory-consolidate` at 03:00 AM) handle background housekeeping. | Done |
| C.4 | **SOP Orchestration** | Cron can directly trigger multi-step SOPs with full state tracking and rollback support. | Done |
| C.5 | **Web UI Control** | Real-time management of schedules, status monitoring, and manual triggers. | Done |

### Built-in Maintenance Jobs
| Job ID | Schedule | Purpose |
|---|---|---|
| `sys-memory-consolidate` | `0 0 3 * * *` | Removes near-duplicate memory chunks and consolidates `agent_notes` daily. `Memory.md` is not touched. |
| `sys-trace-prune` | `0 30 2 * * *` | Keeps the newest 5000 agent traces and deletes older ones, daily. |

---

## Node Host / Remote Execution (Section 20)

OpenClaw's node host lets mobile/desktop devices execute tools for the gateway.

| # | Feature | OpenClaw | GoClaw | Status |
|---|---------|----------|---------|--------|
| 20.1 | Node pairing | Mobile → gateway via QR or manual | — | **TODO** |
| 20.2 | Node capabilities | Advertise capabilities (camera, shell, etc.) | — | **TODO** |
| 20.3 | `node.invoke` RPC | Gateway requests node to run a tool | — | **TODO** |
| 20.4 | Headless node | `openclaw node start` — CLI-only | — | **TODO** |
| 20.5 | Mobile as node | iOS/Android run `system.run`, camera, SMS | — | **TODO** |
| 20.6 | Browser proxy | Node hosts browser automation | — | **TODO** |
| 20.7 | Node Pending Work | Queue for offline nodes | Partial | Enqueue/drain/ack internal (not routed) |

---

## OpenClaw vs GoClaw Ecosystem Comparison

| Aspect | OpenClaw | GoClaw |
|--------|----------|---------|
| **Plugin system** | npm-based, JS class SDK | **Agent Plugins** (VS Code layout) installed from zips, GitHub, archives and marketplaces; Go extension manifests discovered, not loaded |
| **Plugin types** | Channel, provider, tool | Agent Plugins bundle subagents, instructions, skills, hooks and MCP servers; no channel, provider or tool plugins |
| **Hooks** | 26 events, no priority | **Admin hooks on tool calls (block / notify / webhook) + 12 observe-only gateway events, priority-based dispatch** |
| **Skills registry** | Clawhub marketplace | **Skills in `skills-registry/`, installed by path or URL + security scanner** |
| **Cron system** | ✅ | ✅ + **auto-restore on restart** |
| **Node host** | Full RPC system | Not started |

**Coverage:** Agent Plugins, admin hooks, the gateway event registry, the skills scanner and the cron system are in place; Go extensions are discovered but not loaded, skills are installed by path, URL or GitHub repository (there is no install by name), and the node host is not started.