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": {
          "platformUrl": "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

Platform

| Config Key | Env Var | Default | Description | |---|---|---|---| | platformUrl | BEEOS_PLATFORM_URL | — | (Required) Base URL of the BeeOS platform 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 | 300000 | Timeout for LLM prompt responses (ms) | | bridge.historyPendingTimeoutMs | — | — | Timeout for history replay pending state (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) | | loadReplayIdleTimeoutMs | BEEOS_LOAD_REPLAY_IDLE_TIMEOUT_MS | 15000 | Idle timeout for history replay loading (ms) | | cronFlushTimeoutMs | BEEOS_CRON_FLUSH_TIMEOUT_MS | 120000 | Timeout for cron flush operations (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": {
          "platformUrl": "https://api.beeos.ai",
          "bridge": {
            "url": "wss://bridge.beeos.ai",
            "keyFile": "/home/agent/.openclaw/bridge-key.json",
            "service": "acp",
            "shell": {
              "enabled": true
            },
            "promptTimeoutMs": 300000
          },
          "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

License

MIT