Beam plugin

• POST /api/v1/beam/sessions
• the read-only Beam session catalog in the Control UI sidebar

​

Enable

openclaw plugins enable beam
openclaw gateway restart

{
  plugins: {
    entries: {
      beam: { enabled: true },
    },
  },
}

openclaw plugins disable beam
openclaw gateway restart

​

Authentication

• With gateway.auth.mode: "trusted-proxy", send requests through the configured identity-aware proxy. Beam relies on Gateway authentication but does not persist proxy identity headers as uploader attribution.
• With token or password auth, send Authorization: Bearer <gateway-token-or-password>.
• Do not enable Beam with gateway.auth.mode: "none" unless another private ingress fully authenticates every request.

cloudflared access login https://gateway.example.com
cloudflared access curl https://gateway.example.com/api/v1/beam/sessions \
  -H 'Content-Type: application/json' \
  --data-binary @sanitized-beam.json

​

Request

POST /api/v1/beam/sessions
Content-Type: application/json

{
  "version": 1,
  "beamId": "0123456789abcdef0123456789abcdef",
  "source": "claude",
  "title": "Fix the upload flow",
  "updatedAt": "2026-07-20T12:00:00.000Z",
  "completed": false,
  "items": [
    { "type": "userMessage", "text": "Fix the upload flow." },
    { "type": "agentMessage", "text": "Implemented and tested." },
    { "type": "other", "text": "3 read, 2 write, 1 execute; raw tool outputs dropped: 4" }
  ]
}

{
  "ok": true,
  "beamId": "0123456789abcdef0123456789abcdef",
  "url": "/chat?session=catalog%3Abeam%3Agateway%3A0123456789abcdef0123456789abcdef"
}

​

Storage and visibility

• at most 500 sessions
• seven-day retention refreshed by each update
• oldest-entry eviction when the catalog reaches its bound
• server receipt time controls catalog ordering; clients cannot move themselves ahead with a forged timestamp

​

Security boundary

• It has no continueSession, archive, terminal, tool, or node capability.
• It accepts text-only normalized transcript items, not HTML, scripts, archives, attachments, or server-fetched URLs.
• The official skill removes raw tool results, reasoning, prompts, local paths, credentials, cookies, and auth material before upload.
• The receiver still treats every transcript as untrusted text. Copying a beamed transcript into a new agent session is a separate operator action.
• Requests are rate-limited and concurrency-limited before the body is read.

​

Mirroring

{
  plugins: {
    entries: {
      beam: {
        enabled: true,
        config: {
          mirror: {
            endpoint: "https://team.example.com/api/v1/beam/sessions",
            token: { source: "env", provider: "default", id: "BEAM_TEAM_TOKEN" },
            catalogs: ["claude", "codex"],
          },
        },
      },
    },
  },
}

• endpoint (required): the remote receiver URL. HTTPS is enforced for non-loopback hosts; plaintext http:// is accepted only for localhost/127.0.0.1/::1 development.
• token: Gateway credential for the remote receiver, sent as Authorization: Bearer. Accepts a plain string or a secret reference; a configured-but-unresolved token pauses mirroring instead of sending unauthenticated requests. Deployments fronted by an identity-aware proxy need an ingress that accepts this bearer credential.
• catalogs (required): the session catalog ids to mirror, as explicit per-catalog consent — an omitted or empty list mirrors nothing. The local beam receiver catalog is always excluded so two mirrored Gateways cannot re-mirror each other’s rows.
• pollSeconds (default 30, minimum 10): how often the mirror scans local catalogs.
• activeWindowMinutes (default 180): sessions with newer activity than this window count as live and stay mirrored; when a session goes idle past the window the mirror sends one final completed update.

​

Troubleshooting

​

Related

• Control UI
• Operator scopes
• Trusted proxy auth
• Plugin management