Module @karmaniverous/jeeves-watcher-openclaw

@karmaniverous/jeeves-watcher-openclaw

OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools for your AI agent.

Prerequisites

A running jeeves-watcher service with its REST API accessible.

Installation

The plugin is a standard OpenClaw plugin with no installer of its own. On a Jeeves box, jeeves install (from @karmaniverous/jeeves 0.6+) installs it and writes its config:

jeeves install watcher --config-root /srv/jeeves/config

Or install it directly with the OpenClaw CLI and set the config yourself:

openclaw plugins install npm:@karmaniverous/jeeves-watcher-openclaw@<version> --pin --accept-capabilities

The plugin registers an always-in-context rule set through OpenClaw's before_prompt_build hook, so it needs plugins.entries.jeeves-watcher-openclaw.hooks.allowConversationAccess: true. jeeves install / jeeves update grant this automatically (the hook is declared in package.json under jeeves.conversationHooks).

Restart the OpenClaw gateway to apply changes.

Configuration

Plugin config lives in openclaw.json under plugins.entries.jeeves-watcher-openclaw.config:

{
  "apiUrl": "http://127.0.0.1:1936",
  "apiKey": "<the service api.apiKey>",
  "configRoot": "/srv/jeeves/config"
}

apiUrl: jeeves-watcher API base URL (default: http://127.0.0.1:1936; env fallback JEEVES_WATCHER_URL).
apiKey (optional): bearer key sent as Authorization: Bearer <key> on every watcher API request; it must match the service's api.apiKey. Env fallback JEEVES_WATCHER_API_KEY. Resolved on every call and never logged. Unset (the default): no header is sent, exactly as before. If the service requires a key and it is missing or wrong, tools return an HTTP 401 unauthorized error naming both ways to set it. Every other API error reads HTTP <status> <code>: <message>, with the server's error code. Only watcher_status (GET /status is always open) and watcher_service (no HTTP) do not use it.
configRoot: platform config root path, used by @karmaniverous/jeeves core to derive {configRoot}/jeeves-watcher/. No default. Set it in plugin config or via the JEEVES_CONFIG_ROOT env var.

configRoot is resolved lazily. The plugin always registers, even before its config is written (openclaw plugins install activates a plugin before jeeves install writes plugins.entries.<id>.config). While configRoot is unset the plugin logs one warning at registration. Gating is per call: only invocations that actually read configRoot are gated. Today that is exactly watcher_service with action: "install" (it derives the service config path from configRoot); it returns an error naming both ways to set it. Other watcher_service actions (uninstall, start, stop, restart, status) address the OS service by name, and every other tool only calls the watcher HTTP API, so they keep working without configRoot. Core is initialized on the first gated call after it resolves.

Architecture

Plugin Architecture

Jeeves Platform Integration

The plugin builds on @karmaniverous/jeeves 0.7 (static-content core since 0.6). It writes no workspace files and starts no timers:

Always-in-context rules: the watcher escalation, scan-first and search-first rules and score guidance are injected on every turn via before_prompt_build (registerPromptContext). They replace the v0.x TOOLS.md ## Watcher section.
Live state: served by tools (watcher_status, watcher_config) rather than a refreshed file.
Skill: jeeves-watcher ships in the package and is declared in openclaw.plugin.json (skills).
Static platform content (SOUL.md / AGENTS.md blocks) is rendered only by jeeves install.

Tools

Tool	Description
`watcher_status`	Service health, uptime, and collection stats
`watcher_search`	Semantic search across indexed documents
`watcher_enrich`	Set or update document metadata by file path
`watcher_config`	Query the effective runtime config via JSONPath
`watcher_walk`	List watched files matching globs
`watcher_validate`	Validate a candidate config, optionally testing file paths
`watcher_config_apply`	Apply a config patch (response config redacted)
`watcher_reindex`	Trigger a scoped reindex with blast area plan
`watcher_scan`	Filter-only point query with cursor pagination
`watcher_issues`	List processing issues (file paths and source references)
`watcher_service`	Manage watcher background service (install/uninstall/start/stop/restart/status)
`watcher_vcs_status`	Version tracking health: enabled state, tracked roots, remote status
`watcher_vcs_history`	Query change history by path or glob with optional date range
`watcher_vcs_show`	Retrieve file content at a specific version
`watcher_vcs_diff`	Show changes between two versions, or between a version and current
`watcher_vcs_revert`	Undo changes by restoring files to a specific version
`watcher_vcs_exclude`	Exclude or re-include paths from version tracking
`watcher_vcs_check`	Check whether a path is excluded from version tracking and why

Direct tools under OpenClaw Tool Search

OpenClaw 2026.9+ Tool Search moves optional plugin tools out of the model-visible tool list into a hidden catalog reachable only through tool_search. watcher_search and watcher_scan are registered with catalogMode: 'direct-only', so they stay directly visible to the model.

Why: semantic search only pays off if the model reaches for it before falling back to grep or filesystem walks. Hidden behind a catalog lookup, it is rarely discovered and archive recall silently degrades.

Trade-off: these two tools always occupy space in the model's tool list, and they do not appear in tool_search results. All other watcher_* tools remain catalog-eligible. On OpenClaw versions without Tool Search the property is ignored.

Stopgap: some models route direct tools through tool_call, which fails because they are not in the catalog, so both descriptions end with "This is a direct tool: call it directly, never through tool_call." until openclaw/openclaw#161022 is fixed.

Documentation

Full docs for the jeeves-watcher service and this plugin:

docs.karmanivero.us/jeeves-watcher

License

BSD-3-Clause

Functions

default