@askman-dev/bricks-openclaw-plugin

@askman-dev/bricks-openclaw-plugin is the Bricks channel plugin for OpenClaw.

• Canonical channel/plugin id: dev-askman-bricks (must stay unchanged)
• Distribution target: npm + ClawHub
• Runtime mode: pull-only Bricks event runner managed by OpenClaw gateway

Public install flow (external users)

Install from package registry (OpenClaw resolves ClawHub first, then npm):

openclaw plugins install @askman-dev/bricks-openclaw-plugin
openclaw gateway restart

Inspect the installed plugin metadata:

openclaw plugins inspect dev-askman-bricks

Development-only local install is still supported, but external users should prefer package install instead of cloning this repository.

Configure / onboarding flow

After install, run one of:

openclaw onboard
# or
openclaw configure

Choose dev-askman-bricks (Bricks), then provide:

• BRICKS_BASE_URL
• BRICKS_PLUGIN_ID (normally dev-askman-bricks)
• BRICKS_PLATFORM_TOKEN

Equivalent direct config commands:

openclaw config set channels.dev-askman-bricks.BRICKS_BASE_URL https://your-bricks-api.example.com
openclaw config set channels.dev-askman-bricks.BRICKS_PLUGIN_ID dev-askman-bricks
openclaw config set channels.dev-askman-bricks.BRICKS_PLATFORM_TOKEN 'your-jwt-token'
openclaw config validate
openclaw gateway restart

Update flow

Update an existing installation:

openclaw plugins update dev-askman-bricks
openclaw gateway restart

If you changed channel credentials or endpoint, re-run openclaw configure (or openclaw config set ...) and then restart gateway.

Runtime behavior summary

When OpenClaw gateway starts/restarts, the plugin runner is host-managed:

1. Starts on gateway account lifecycle (startAccount)
2. Polls GET /api/v1/platform/events
3. ACKs events via POST /api/v1/platform/events/ack
4. Hands user messages to OpenClaw inbound/session pipeline
5. Writes assistant output via POST/PATCH /api/v1/platform/messages
6. Stops gracefully on gateway shutdown via AbortSignal

Troubleshooting

Plugin installed but channel not responding

• Verify config exists under channels.dev-askman-bricks.
• Validate config and restart gateway:

openclaw config validate
openclaw gateway restart

Auth / token errors

The plugin validates platform token claims at startup (typ=platform_plugin, matching pluginId, and required userId). Regenerate token if claims are invalid.

Packaging caveat

openclaw plugins install uses npm install --ignore-scripts. Do not rely on npm postinstall to write configuration; always configure via OpenClaw onboarding/config commands.

Development-only local flow

Use local path or linked install only while developing this repository:

openclaw plugins install ./apps/node_openclaw_plugin
# or
openclaw plugins install -l ./apps/node_openclaw_plugin
openclaw gateway restart

Standalone runner debug (outside gateway lifecycle):

cd apps/node_openclaw_plugin
npm install
npm run build
npm start

Optional runtime environment variables

| Variable | Required | Description | |---|---|---| | OPENCLAW_PLUGIN_POLL_INTERVAL_MS | No | Poll interval in ms (default 2000) | | OPENCLAW_PLUGIN_DEFAULT_CURSOR | No | Initial cursor (default cur_0) | | OPENCLAW_PLUGIN_STATE_FILE | No | Local state file path (default ~/.bricks/node_openclaw_plugin_state.json) | | OPENCLAW_PLUGIN_ASSISTANT_NAME | No | Assistant name in output messages (default Node OpenClaw Plugin) |