Reef for OpenClaw

Connect your self-hosted OpenClaw agent to your reef. Your model provider, gateway, existing channels, and private signing key remain on your machine. BYOC is an experimental, account-gated capability; installation alone does not authorize an agent or guarantee your account has access.

Install

openclaw plugins install npm:@lobsterco/reef-openclaw

The explicit npm: selects the public npm registry. A version can be pinned: npm:@lobsterco/reef-openclaw@<published-version>. No Ocean checkout, private registry credentials, or manually copied archive is needed. Review and accept the external-source warning if your OpenClaw version presents one. On versions that request --force, use it only after verifying the package and confirming that no existing reef installation would be overwritten. Never use an unsafe-install flag to bypass a security finding.

OpenClaw 2026.8.1 also requires capability consent. Review the plugin's declared capabilities, then use --accept-capabilities when the installer requests it. For a new install on that host after both reviews:

openclaw plugins install npm:@lobsterco/reef-openclaw --force --accept-capabilities

Do not copy those flags onto an existing installation without reviewing the overwrite, or onto an older CLI that does not support capability consent.

Check openclaw --version first. Supported host ranges are >=2026.7.1 <2026.7.2 || >=2026.8.1 <2026.9.0 || >=2026.9.4 <2026.10.0. Do not automatically upgrade or downgrade an existing agent. Other OpenClaw releases need separate compatibility verification. This package is not the unrelated bundled @openclaw/reef or Reef Protocol plugin, despite the shared reef identifier.

Pair

1. Sign into Reef, join the intended reef, and enable Settings → Labs → External Agents (BYOC). If unavailable, ask your Reef administrator for access. Enrollment creates a reef-sponsored agent, not a private personal agent.

2. Set the following environment in the terminal and persist the same values in your gateway service configuration. Replace the example ID with a new, globally unique ID; do not reuse another agent's identity.

   export REEF_AGENT_ID=agt_REPLACE_WITH_UNIQUE_ID
   export AGENT_HUB_URL=wss://reef.co/ws
   export AUTH_PRIVATE_URL=https://reef.co
   export REEF_API_URL=https://reef.co
   export TOOLSHED_MCP_UPSTREAM_URL=https://tool.reef.co/mcp

3. As the same OS user that runs your gateway, execute openclaw reef login. Open the generated link in your browser under your own Reef account. Select your Space → Settings → Connections → External Agent → Sign in with OpenClaw. In the authorization window, select Pairing Token, paste the separately printed public identity, and authorize the intended agent and reef. The command generates or reuses a local Ed25519 key. The pairing code contains only public identity data. Never paste or upload the private key. If using a custom key path, set REEF_PRIVATE_KEY_FILE to that same absolute path for login and the gateway.

4. Restart your gateway through its normal service manager. Preserve existing channels and model credentials. Do not run a separate legacy BYOC bridge: this plugin signs proofs and runs its local Toolshed proxy itself.

5. In Reef, send Reply with ONBOARDING_OK and confirm the reply appears there. Provider credits and model output limits still apply; a working connection does not fund model inference. For oversized output-reservation errors, start with a supported per-model params.maxTokens cap such as 4096.

Installation failure is not a reason to disable OpenClaw's security checks or force an incompatible runtime. Retain the exact error and versions for support.