beeos-claw

OpenClaw plugin that bridges the BeeOS platform with the local OpenClaw Gateway. Provides ACP (Agent Communication Protocol) bridge, file transfer, terminal access, and observability.

Install

npm install beeos-claw

Quick Start

Add to your OpenClaw configuration (~/.openclaw/openclaw.json):

{
  "plugins": {
    "entries": {
      "beeos-claw": {
        "package": "beeos-claw",
        "enabled": true,
        "config": {
          "agentGatewayUrl": "https://api.beeos.ai",
          "bridge": {
            "url": "wss://bridge.beeos.ai",
            "keyFile": "~/.openclaw/bridge-key.json"
          }
        }
      }
    }
  }
}

Connection Mode

The agent initiates an outbound WebSocket connection to the Bridge server (Phone-Home model). No inbound ports are required — the agent never listens as an ACP server.

Requires both bridge.url and bridge.keyFile to be configured.

Configuration

Configuration is resolved from three sources in priority order:

1. Plugin config — plugins.entries.beeos-claw.config in openclaw.json
2. Environment variables — prefixed with BEEOS_ or BRIDGE_
3. Defaults

Agent Gateway

| Config Key | Env Var | Default | Description | |---|---|---|---| | agentGatewayUrl | AGENT_GATEWAY_URL | — | (Required) Base URL of the Agent Gateway API |

Bridge

| Config Key | Env Var | Default | Description | |---|---|---|---| | bridge.url | BRIDGE_URL | — | Bridge server WebSocket URL | | bridge.keyFile | BRIDGE_KEY_FILE | — | Path to Ed25519 key file for Bridge authentication. Auto-generates if file doesn't exist. | | bridge.service | BRIDGE_SERVICE | acp | Service type for Bridge registration. One of: acp, screen, desktop, shell | | bridge.mode | — | — | Bridge operational mode | | bridge.shell.enabled | BEEOS_SHELL_ENABLED | true | Enable web-SSH / terminal bridge support | | bridge.promptTimeoutMs | BEEOS_PROMPT_TIMEOUT_MS | 600000 | Timeout for LLM prompt responses (ms) |

Gateway (OpenClaw Gateway Connection)

| Config Key | Env Var | Default | Description | |---|---|---|---| | gateway.url | BEEOS_GATEWAY_URL | ws://127.0.0.1:18789 | WebSocket URL of the local OpenClaw Gateway | | gateway.token | BEEOS_GATEWAY_TOKEN | — | Gateway authentication token. Also read from openclaw.json at gateway.auth.token. | | gateway.protocol | — | 3 | Gateway protocol version | | gateway.clientId | — | beeos-claw-{pid} | Client ID for the Gateway connection | | gateway.agentId | — | main | Agent ID to use |

Terminal

| Config Key | Env Var | Default | Description | |---|---|---|---| | terminalWsPort | BEEOS_TERMINAL_WS_PORT | 18801 | Port for the terminal WebSocket server | | terminalWsAllowedOrigins | BEEOS_TERMINAL_WS_ALLOWED_ORIGINS | localhost,127.0.0.1,::1 | Comma-separated allowed origins for terminal WS |

Reconnect

| Config Key | Env Var | Default | Description | |---|---|---|---| | retry.baseMs | — | 1000 | Base delay for exponential backoff reconnect (ms) | | retry.maxMs | — | 600000 | Maximum reconnect delay (ms) | | retry.maxAttempts | — | 0 | Maximum reconnect attempts. 0 = unlimited. |

Logging & Observability

| Config Key | Env Var | Default | Description | |---|---|---|---| | log.enabled | BEEOS_LOG_ENABLED | true | Enable structured JSONL observability logs | | log.verbose | — | false | Enable verbose debug logging | | log.dir | — | ~/.openclaw/beeos-logs | Directory for rolling JSONL log files |

Advanced Timeouts

| Config Key | Env Var | Default | Description | |---|---|---|---| | streamIdleTimeoutMs | BEEOS_STREAM_IDLE_TIMEOUT_MS | 15000 | Idle timeout for streaming responses (ms) | | streamStaleTimeoutMs | BEEOS_STREAM_STALE_TIMEOUT_MS | 600000 | Stale timeout for abandoned streams (ms) | | cronSignalWindowMs | BEEOS_CRON_SIGNAL_WINDOW_MS | 60000 | Window for cron signal batching (ms) |

Full Configuration Example

{
  "plugins": {
    "entries": {
      "beeos-claw": {
        "package": "beeos-claw",
        "enabled": true,
        "config": {
          "agentGatewayUrl": "https://api.beeos.ai",
          "bridge": {
            "url": "wss://bridge.beeos.ai",
            "keyFile": "/home/agent/.openclaw/bridge-key.json",
            "service": "acp",
            "shell": {
              "enabled": true
            },
            "promptTimeoutMs": 600000
          },
          "gateway": {
            "url": "ws://127.0.0.1:18789",
            "protocol": 3,
            "agentId": "main"
          },
          "retry": {
            "baseMs": 1000,
            "maxMs": 600000,
            "maxAttempts": 0
          },
          "log": {
            "enabled": true,
            "verbose": false,
            "dir": "/home/agent/.openclaw/beeos-logs"
          }
        }
      }
    }
  }
}

Features

ACP Bridge

Connects local OpenClaw agents to the BeeOS platform via the Agent Communication Protocol. Handles prompt routing, streaming responses, session history replay, and tool call forwarding.

File Transfer

Provides the beeos_upload_file tool for agents to upload files from the sandbox to BeeOS platform storage. Also supports file staging via the POST /beeos/files/stage HTTP endpoint for downloading files from the platform into the agent sandbox.

Terminal Bridge

When bridge.shell.enabled is true, the plugin starts a WebSocket server for web-SSH / terminal access. Remote users can open terminal sessions through the Bridge connection.

Observability

When log.enabled is true, the plugin writes structured JSONL logs covering:

• Plugin lifecycle events (startup, config resolution)
• ACP message flow (prompts, responses, tool calls)
• Bridge connection events (connect, disconnect, auth)
• Upload tool execution results
• Terminal session events

Logs are written to rolling files in log.dir with automatic rotation and sensitive data redaction (tokens, large base64 payloads).

Requirements

• Node.js >= 18
• OpenClaw runtime

Release Channels

beeos-claw publishes to two npm dist-tags so that staging validation never affects production agent pods:

| Channel | Git branch | Version shape | npm dist-tag | Docker image tag | |---|---|---|---|---| | production | main | X.Y.Z (plain SemVer, e.g. 0.2.41) | latest | openclaw-desktop:latest, production-<sha> | | staging | staging | X.Y.Z-staging.N (pre-release, e.g. 0.2.41-staging.0) | staging | openclaw-desktop:staging-latest, staging-<sha> |

The publish workflow .github/workflows/publish.yml inspects the version in package.json:

• If the version contains a -staging. / -rc. / -beta. / -alpha. suffix → published with --tag staging, downstream image built with channel=staging.
• Otherwise → published with --tag latest, downstream image built with channel=production.

Release to staging

git checkout staging
git merge main                                    # or cherry-pick the commits you want to ship
npm version prerelease --preid=staging --no-git-tag-version
git commit -am "chore: release $(node -p "require('./package.json').version")"
git push origin staging

CI publishes [email protected] with dist-tag=staging, then triggers beeos-openclaw to rebuild openclaw-desktop:staging-latest. Consumers pulling beeos-claw@latest from npm or openclaw-desktop:latest from ECR are not affected.

Promote to production

After staging validation:

git checkout main
git merge staging                                 # brings pre-release commits into main
npm version 0.X.Y --no-git-tag-version            # strip the -staging.N suffix
git commit -am "chore: release $(node -p "require('./package.json').version")"
git push origin main

CI publishes [email protected] with dist-tag=latest, then triggers beeos-openclaw to rebuild openclaw-desktop:latest (floating production tag, Docker convention) plus an immutable openclaw-desktop:production-<sha> for audit/rollback.

Install from a specific channel (for local dev / debugging)

npm install beeos-claw              # always resolves to production (dist-tag=latest)
npm install beeos-claw@staging      # latest staging pre-release
npm install [email protected]   # pin an exact pre-release build

Pre-release versions never match semver ranges like ^0.2.40, so production consumers are not silently upgraded to staging builds.

License

MIT