What is this?

This is the server-side plugin for BetterClaw, an iOS app that connects your iPhone's sensors to your OpenClaw AI agent. The app streams device events (location, health, geofences) to your gateway — this plugin decides what to do with them.

The plugin differentiates between free and premium tiers:

• Free — passive context store. The agent can pull device snapshots via get_context, but no events are pushed proactively.
• Premium — full smart mode pipeline with rules-based filtering, LLM triage, engagement tracking, and a daily learner that adapts to your preferences.

Features

• Tier-Aware Routing — check_tier tool tells the agent whether to use node commands (premium, fresh data) or get_context (free, cached snapshots). Includes a 24h cache TTL so the agent doesn't re-check every turn.
• Free = Pull-Only — Events are stored for context but never triaged or pushed. get_context with staleness indicators (dataAgeSeconds) is the only data source.
• Premium Smart Mode — Rules engine + LLM triage with fail-closed error handling and budget-aware prompts. Daily push budget prevents event spam.
• Engagement Tracking — Deterministic transcript scanner finds pushed messages by timestamp, then an LLM classifies user engagement as engaged, ignored, or unclear. Feeds into the learner.
• Adaptive Learner — Daily subagent builds a simplified triage profile (summary + interruptionTolerance) from event history, engagement data, and workspace memory.
• Calibration Period — First 3 days after install, triage runs in rules-only mode while the system collects engagement data. Skipped automatically for users upgrading from v2.
• Device Context — Rolling state snapshot with per-field timestamps and dataAgeSeconds: GPS, zone occupancy, health metrics, activity classification.
• Pattern Recognition — Daily analysis computes location routines, health trends (7d/30d baselines), and event frequency stats.
• Per-Device Config — iOS app can override push budget at runtime via RPC.
• Shortcuts Result Bridge — Receives BetterClaw Runner callback results from iOS and can deliver late shortcut results back into the active agent session.
• Agent Tools — check_tier for routing decisions, get_context for patterns/trends/cached state, and edit_routing_rules for Smart Mode routing policy edits.
• Agent Profile Sync — Optional generated TOOLS.md block with current tier, active node ID, and fast-path examples. The plugin updates only its marked block and skips unchanged writes.
• CLI Setup — openclaw betterclaw setup configures gateway allowedCommands, tool allow-list entries, and optional agent profile maintenance automatically.

Requirements

• BetterClaw iOS app installed and connected to your gateway
• OpenClaw gateway (2026.5.5+)

Install

openclaw plugins install @better_openclaw/betterclaw
openclaw betterclaw setup   # configures gateway commands/tools and prompts for TOOLS.md profile sync
openclaw gateway restart    # apply config changes when setup reports changes

Installing from a source checkout requires a build first, because OpenClaw loads installed plugins from compiled JavaScript. Install the packed artifact instead of the checkout directory so OpenClaw scans the same file set that would ship to npm:

git clone https://github.com/BetterClaw-app/betterclaw.git
cd betterclaw
npm install
npm run build
TARBALL=$(npm pack --silent)
openclaw plugins install "./$TARBALL"
openclaw betterclaw setup
openclaw gateway restart

Non-interactive setup scripts should pass an explicit profile choice:

openclaw betterclaw setup --agent-profile yes
openclaw betterclaw setup --agent-profile no
openclaw betterclaw setup --dry-run --agent-profile yes

When enabled, the plugin maintains this generated range inside the default agent workspace TOOLS.md:

<!-- betterclaw-device-profile:start v1 -->
...
<!-- betterclaw-device-profile:end -->

The block includes tier, active BetterClaw iOS node ID, recommended data path, and examples for location, health, and shortcut requests.

Update

To update an existing install to the latest stable release:

openclaw plugins update betterclaw
openclaw betterclaw setup
openclaw gateway restart    # apply config changes when setup reports changes

Preview the change first:

openclaw plugins update betterclaw --dry-run

To opt into the current dev prerelease:

openclaw plugins update @better_openclaw/betterclaw@dev
openclaw betterclaw setup
openclaw gateway restart    # apply config changes when setup reports changes

Configure

Add to your openclaw.json:

{
  "plugins": {
    "entries": {
      "betterclaw": {
        "enabled": true,
        "config": {
          "triageModel": "primary",
          "pushBudgetPerDay": 10,
          "patternWindowDays": 14,
          "analysisHour": 5,
          "calibrationDays": 3
        }
      }
    }
  }
}

All config keys are optional — defaults are shown above.

Config Reference

| Key | Default | Description | |-----|---------|-------------| | triageModel | primary | Model for per-event triage and engagement classification. primary/default uses OpenClaw's default session model without requesting a plugin model override. Concrete model refs request a subagent model override. | | triageApiBase | -- | Optional base URL for an OpenAI-compatible endpoint. When set, triage uses direct HTTP instead of OpenClaw's subagent runtime. | | pushBudgetPerDay | 10 | Max events forwarded to the agent per day | | patternWindowDays | 14 | Days of event history used for pattern computation | | analysisHour | 5 | Hour (0-23, system timezone) for daily pattern + learner analysis | | calibrationDays | 3 | Days of rules-only triage before learner profile kicks in |

Migration from v2: llmModel still works as a deprecated alias for triageModel. proactiveEnabled is ignored (proactive triggers removed in v3).

To force triage onto a specific model through OpenClaw's subagent runtime, the gateway must explicitly allow BetterClaw to request model overrides:

{
  "plugins": {
    "entries": {
      "betterclaw": {
        "subagent": {
          "allowModelOverride": true,
          "allowedModels": ["anthropic/claude-sonnet-4-5"]
        },
        "config": {
          "triageModel": "anthropic/claude-sonnet-4-5"
        }
      }
    }
  }
}

If triageApiBase is set, triageModel is sent to that OpenAI-compatible HTTP endpoint instead of OpenClaw's subagent runtime.

How It Works

Event Pipeline

Every device event from the BetterClaw app goes through the plugin:

Background Services

• Pattern Engine + Reaction Scanner + Learner (daily at analysisHour) — Computes location routines, health trends, event stats. Then scans session transcripts for engagement with past pushes (deterministic timestamp search + LLM classification). Finally runs a subagent to build a personalized triage profile from engagement data and workspace memory.

Agent Tools

| Tool | Purpose | |------|---------| | check_tier | Returns tier + routing instructions + cache TTL. No device data. Call first. | | get_context | Returns patterns, trends, zone state, cached device snapshots with dataAgeSeconds. | | edit_routing_rules | Reads or updates Smart Mode routing rules with audit logging. |

Gateway RPCs

| RPC | Direction | Purpose | |-----|-----------|---------| | betterclaw.event | iOS -> plugin | Send a device event for processing | | betterclaw.ping | iOS -> plugin | Heartbeat: sync tier + smartMode, init calibration | | betterclaw.config | iOS -> plugin | Per-device settings override | | betterclaw.context | iOS -> plugin | Full context for iOS Context tab (includes calibrating flag) | | betterclaw.snapshot | iOS -> plugin | Bulk device state catch-up | | betterclaw.learn | iOS -> plugin | Trigger on-demand triage profile learning | | betterclaw.logs | iOS -> plugin | Paginated diagnostic log export | | betterclaw.shortcutResult | iOS -> plugin | Async Shortcuts runner result callback |

Commands

| Command | Description | |---------|-------------| | /bc | Show current device context snapshot in chat |

Compatibility

| Plugin | BetterClaw iOS | OpenClaw | |--------|----------------|----------| | 3.x | 2.x+ | 2026.4.14+ | | 2.x | 2.x+ | 2025.12+ | | 1.x | 1.x | 2025.12+ |

License

AGPL-3.0 -- Free to use, modify, and self-host. Derivative works must remain open source.