@keepershub/openclaw-keepershub

KeeperHub workflow automation plugin for OpenClaw. Wraps the full KeeperHub MCP API as native OpenClaw agent tools so your OpenClaw agent can create, manage, and execute on-chain workflows, monitor smart contracts, and interact with DeFi protocols through natural language.

Features

• 28 typed tools covering every KeeperHub MCP operation
• Workflow management — list, get, create, update, delete, execute, search
• Template browser — search, inspect, and deploy pre-built workflow templates
• DeFi protocol actions — read Aave, Chainlink, Morpho, Uniswap, Compound, Lido, Maker positions directly
• On-chain execution — transfer tokens and call smart contracts via your KeeperHub wallet integration
• Plugin / integration discovery — explore available action schemas and configured credentials
• AI workflow generation — describe a workflow in natural language and let KeeperHub AI build the JSON definition for you
• Marketplace integration — search and invoke publicly listed workflows; transparent fallback to org workflows
• Connection status tool — kh_status reports the active org and workflow count
• Auto-resuming MCP session — handles 401 / 404 session expiry transparently

Installation

After publishing (see Publishing below), install by package name. OpenClaw resolves bare specs against ClawHub first, then npm (Plugins doc):

openclaw plugins install @keepershub/openclaw-keepershub

Force the resolver when you want only one registry:

openclaw plugins install clawhub:@keepershub/openclaw-keepershub
openclaw plugins install npm:@keepershub/openclaw-keepershub

Restart the Gateway:

openclaw gateway restart

Developing from this repo (not published yet)

Install from the plugin directory path instead of the package name:

openclaw plugins install ./openclaw-plugins/keepershub
openclaw gateway restart

Hook packs vs plugins

If OpenClaw reports “not a valid hook pack”, you are likely pointing a hooks/skill pack resolver at this package. Native OpenClaw plugins are installed with openclaw plugins install …, not the hooks installer.

Configuration

Set your KeeperHub organization API key (starts with kh_) in your OpenClaw config:

{
  "plugins": {
    "entries": {
      "keepershub": {
        "config": {
          "apiKey": "kh_your_key_here"
        }
      }
    }
  }
}

Alternatively, set one of these environment variables (the plugin checks them in order):

KH_API_KEY=kh_your_key_here
KEEPERHUB_API_KEY=kh_your_key_here
KEEPERSHUB_API_KEY=kh_your_key_here

Get an API key at app.keeperhub.com → Avatar → API Keys → Organisation → New API Key.

Verifying the install

openclaw plugins inspect keepershub --runtime --json

Then ask your OpenClaw agent to call kh_status — it will report whether the API key is detected, the active organization id, and the cached workflow count.

Usage

Once installed and configured, the agent can call any of the kh_* tools. Example prompts:

List all my KeeperHub workflows.
Get workflow abc123.
Create a workflow called "ETH Monitor" with a manual trigger.
Execute workflow abc123.
Search templates for monitoring.
Deploy template abc123 as "My Monitor".
Search protocol actions for aave.
Execute protocol action aave/get-user-account-data on network 1 for 0x123...
List my integrations.
What web3 plugins are available in KeeperHub?
Generate a workflow that monitors USDC transfers over $10k and sends a Discord alert.
Show KeeperHub documentation.

Tool reference

All tools are registered as required (always available). No allowlist entry is needed in tools.allow.

Architecture

OpenClaw agent → kh_* tool → KeeperHubClient (singleton)
                              │
                              └─► HTTP POST + mcp-session-id → app.keeperhub.com/mcp
                                  ↑    (401/404 session ⇒ re-initialize and replay)
                                  └── Authorization: Bearer kh_...

The client lazy-initializes the MCP session on the first tool call and caches it per process. Session expiry (401, or 404 with a session-related body) triggers a transparent re-initialize and replay of the original call.

Development

# Install dependencies
bun install
# or: pnpm install

# Run tests
bun test

# Build (generates dist/)
bun run build

The plugin uses TypeBox for parameter schemas (the schema format OpenClaw expects in api.registerTool({ parameters })).

The "files" field in package.json intentionally excludes src/__tests__ so published tarballs stay lean.

Publishing

Publishing requires credentials on your machine; nothing in this repo can publish without npm / ClawHub auth.

1. Prerequisites

• npm account with permission to publish the @keepershub scope (create the org on npmjs.com or change "name" in package.json to a scope you own).
• Built artifacts: dist/ must exist before publish (prepublishOnly runs tsc).
• Install the ClawHub CLI if you use ClawHub: npm i -g clawhub (ClawHub).

2. Publish to npm

From openclaw-plugins/keepershub/:

npm login
npm publish --access public

Dry-run (contents only, no upload):

npm publish --dry-run

After npm lists the package, users can install with:

openclaw plugins install npm:@keepershub/openclaw-keepershub
# or bare spec (ClawHub first, then npm):
openclaw plugins install @keepershub/openclaw-keepershub

3. Publish to ClawHub (recommended discovery path)

Login once:

clawhub login

Publish from this folder or from GitHub (ClawHub plugins):

cd openclaw-plugins/keepershub
clawhub package publish . --dry-run
clawhub package publish .

Then install:

openclaw plugins install clawhub:@keepershub/openclaw-keepershub

See the OpenClaw plugin building guide for manifest and compatibility notes.

Related

• openclaw.plugin.json — plugin manifest with the full contracts.tools list
• Eliza version — the original ElizaOS port this plugin mirrors

License

MIT