@reefclaw/openclaw-plugin

The ReefClaw trading plugin for OpenClaw. It gives an OpenClaw agent a supervised trading toolkit and connects it to the operator's ReefClaw dashboard. Everything runs on the operator's own machine; ReefClaw's servers host the dashboard, a relay and a market-data API, and never execute trades.

This file is the plain-language ledger of what the package does on the machine it is installed on: what runs, what it writes, what it sends, what it never does, and how to switch each part off. Every line is checkable against the shipped source.

What runs

• The plugin loads into the OpenClaw gateway at startup (activation.onStartup in the manifest) and registers the trading tools listed under contracts.tools.
• One connector process (the bridge/ folder) is started and supervised by the plugin. It holds the outbound connection to the ReefClaw relay, runs the agent's scheduled heartbeat, and delivers signed instruction updates. If it exits, the plugin restarts it.
• The agent starts in PAPER mode: real market data, simulated fills, no exchange account and no API keys. Moving to real money is a separate step the operator takes from the dashboard (PAPER → MICRO_LIVE → LIVE), and the tools that change mode or store credentials refuse calls that do not carry operator provenance from the dashboard.

What it writes on this machine

Path	What	Why
~/.reefclaw/plugin-config.json (owner-only permissions)	Trading mode, per-box switches, and exchange credentials once the operator adds them	The only place exchange keys ever live; used only to sign requests to the exchange
~/.reefclaw/credential-transport-key.json	A key pair used to receive exchange credentials from the dashboard in encrypted form	So credentials cross the relay encrypted to this box; the private half never leaves it
Other files under ~/.reefclaw/	Paper-trading state, the protective-order ledger, position state, a cached copy of the account's central config, market-data caches	Local bookkeeping so a restart resumes where it left off
~/.openclaw/openclaw.json → skills.entries.reefclaw.config only	The connection token, user id and relay URL the operator pasted	So the connector can reach the operator's own dashboard room. Nothing else in that file is touched, and nothing under gateway is ever written
OpenClaw's cron store	One heartbeat job (reefclaw-heartbeat), created through the gateway's own cron API	The scheduled position review; remove it with the OpenClaw cron commands
The reefclaw skill's SKILL.md in the agent workspace, in ~/.openclaw/skills/, and in this package's skills/ folder	The agent's trading instructions, kept identical in the places OpenClaw reads them	The bundled copy is a bootstrap; the full instructions arrive after connect and are applied only after their Ed25519 signature verifies against a key pinned in this build
The agent's sessions.json (older OpenClaw builds only)	One cached skills-snapshot key is cleared after an instruction update	So the running session re-reads the updated skill; nothing else in that file changes

It reads the agent's heartbeat transcripts (OpenClaw's SQLite store on 2026.9+, JSONL before) to build the heartbeat flight recorder described below.

What leaves this machine

Everything below goes to the operator's own ReefClaw account and nowhere else.

Flow	What is sent	Switch
Dashboard relay	Order, position, balance and agent-state events; dashboard chat both ways	none, it is the product
Journal / trade feed	Fills, position entries, heartbeat reviews and closes with the agent's stated reasoning	none, it is the product
Heartbeat flight recorder	For every heartbeat: the tool calls it made (arguments and results truncated, credential-shaped tools redacted), its final report, the model that answered and raw token counts	RC_HEARTBEAT_RECORDER=off
Shock wakes	Nothing is sent; the connector polls the account's shockWake setting and, when the operator turned it on, delivers up to 8 extra agent turns a day on a sharp market move	RC_SHOCK_WAKE=off
Intelligence	Market-context reads; the plugin sends symbols and parameters, never keys	none, tools degrade without it
Version report	The installed plugin and connector versions, so the dashboard can offer an update; plus, from plugin 0.1.39, an integrity check of the running plugin: whether it runs from the standard install location (a yes/no class, never the path), the process start time, and SHA-256 fingerprints of three of the plugin's own files (index.js, tools/create-order.js, risk/pre-trade-check.js), so a box running stale or modified plugin files can be told apart from the release. Never file contents, never a path, never anything outside the plugin's own files	RC_READINESS_INTEGRITY=off (the integrity part only)

Network access is outbound only: the relay (WebSocket), www.reefclaw.com, the intelligence API, the exchange when credentials are present, and the npm registry only during an operator-triggered update. The package opens no listening port.

What it never does

• It never changes the gateway's auth settings. If the gateway withholds the scope the connector needs, the connector logs the exact manual remedy and stops; the decision stays with the operator.
• It never sends exchange API keys to ReefClaw. A test in this package drives the real outbound clients and asserts no credential reaches the wire. On Hyperliquid the key is an agent key, which cannot withdraw or transfer funds; on Binance the operator is asked to create keys without withdrawal permission.
• It never runs an unpinned install. The install line in the bundled skill names the exact connector release this plugin was published with, and the dashboard's one-click update installs exactly the release ReefClaw's public release endpoint reports. If that lookup fails, the update does not run.
• It never trades real money on its own initiative. Live trading requires credentials and a mode change that only the operator can make from the dashboard; every live position carries exchange-native protective stops; and the operator's pause, flatten and kill controls are never gated behind subscription state.

Switches and removal

Setting	Effect
REEFCLAW_ALLOW_CONNECTOR_UPDATE=0 (or connectorUpdate: "off" in plugin-config.json)	The dashboard's one-click update is refused on this box
RC_HEARTBEAT_RECORDER=off	Heartbeat transcripts are not read or reported
RC_SHOCK_WAKE=off	Shock wakes are never constructed, whatever the account setting says
SKILL_OTA_REQUIRE_SIGNATURE=off	Break-glass: accept an unsigned instruction update on this box (a forged signature is still always refused)

To remove the plugin: uninstall it with OpenClaw's plugin commands, delete ~/.reefclaw/, remove the reefclaw skill folder(s), the skills.entries.reefclaw entry in openclaw.json, and the reefclaw-heartbeat cron job.

Install

• From ClawHub on OpenClaw 2026.8.1 or newer: Control UI → Plugins → Discover → search "reefclaw" → Install, then accept the listed capabilities; or in chat /plugins install clawhub:@reefclaw/openclaw-plugin, then the same command with --accept-capabilities after reading the capability list (the chat command needs commands.plugins: true in openclaw.json).
• Or with the ReefClaw connect installer from npm (@reefclaw/connect), run once in a terminal on the OpenClaw host and pinned to the exact release named in the bundled skill and on the onboarding page.

Support: support@reefclaw.com · https://reefclaw.com