openclaw-channel-bgos

OpenClaw channel plugin for BGOS — chat with your OpenClaw agents inside the BGOS app.

Mirrors the shape of the Telegram plugin: pairing, inbound push + REST backfill, outbound text/buttons/approvals, slash-command manifest sync.

Status

Scaffold — not yet published. Core adapters are implemented and unit-tested. Full wiring into OpenClaw's channel-plugin SDK (the defineChannelPluginEntry wrapper and agent-dispatch hook) happens in Phase 4 against a live OpenClaw gateway.

Prerequisites

• Node.js 20+
• BGOS backend with the /api/v1/integrations/* endpoints (PR #41 merged and deployed — see docs/superpowers/specs/2026-04-20-openclaw-bgos-integration-design.md)
• OpenClaw gateway ≥ 1.0 (for the SDK wrapper in Phase 4)

Install (local dev)

cd openclaw-channel-bgos
npm install
npm run build
npm test   # runs vitest — 30 tests against a mock BGOS server

Pair from OpenClaw CLI

Once published (or npm link-ed into an OpenClaw workspace):

openclaw pair bgos BGOS-ABCD-EF

This calls POST /api/v1/integrations/pair-exchange, stores the raw pairing token at ~/.openclaw/secrets/bgos.json with mode 0600, and echoes the local agent-route catalog back to BGOS so it renders the checklist.

Plugin config (channels.bgos)

{
  "channels": {
    "bgos": {
      "baseUrl": "https://api.brandgrowthos.ai",
      "pairingToken": "<token from CLI>",
      "reconnect": { "initialDelayMs": 1000, "maxDelayMs": 30000 }
    }
  }
}

Or via env: BGOS_BASE_URL + BGOS_PAIRING_TOKEN.

What's inside

• BgosApi — typed axios client with the X-BGOS-Pairing header
• BgosWs — Socket.IO client (pairingToken handshake, exponential-backoff reconnect, REST backfill on reconnect)
• BgosOutbound — sendText / sendButtons / sendApprovalRequest / sendAgentError
• ApprovalHandler — native-approval protocol using __approval__:<decision>:<req_id> callback_data
• CommandsSync — debounced manifest PUT per assistant
• pairBgos(...) — CLI entry for openclaw pair bgos <CODE>
• bgosSetupWizard — defineSetupPluginEntry-compatible setup object
• createBgosChannel(cfg, options) — composes all of the above; returns handles incl. a shutdown()

End-to-end testing (manual — needs a real OpenClaw gateway)

See docs/e2e-manual.md for the human-run recipe (install, pair, tick an agent in BGOS, send a message, assert agent replies).

BGOS agent capabilities

Agents reaching the BGOS app through this plugin should understand BGOS's full capability surface — markdown rendering, inline buttons, ask_user_input, approvals, files, and slash commands. The canonical reference lives at:

hermes-channel-bgos/docs/bgos-agent-capabilities.md

Until OpenClaw ships a formal mechanism for surfacing this to agents at connect time (planned — see the canonical doc's per-plugin section), include a summary of relevant capabilities in your agent's system prompt.

Recent additions (Phase 4, April 2026) — inbound messages from BGOS now carry these read-only fields, surfaced in inbound_message WS payloads and via the REST backfill endpoint:

• replyToId (number | null) — when set, the user is replying to that earlier message; quote a 1-line preview of the replied-to message when relevant.
• forwardedFromMessageId (number | null) — when set, the user forwarded the content from another chat; treat as a quote, not the user's own words.
• isPinned (boolean) + pinnedAt (ISO string | null) — the user marked this important; weight pinned messages first when summarizing.

A new message_pinned WebSocket event ({ message_id, chat_id, user_id, is_pinned, pinned_at }) fires on user:<userId> rooms when the user pins or unpins. The plugin can use this to keep any local pin-state mirror fresh; agents themselves rarely need to subscribe.

Bookmarks are private to the user and not surfaced to agents.

License

MIT © BrandGrowthOS