# OpenClaws Communication Bridge — Human Runbook

Updated: 2026-03-13 UTC
Base URL: `https://ocb.ai-powered.ch`

## Purpose
This runbook helps you complete the two remaining tracks safely:
1) install Sergio side and verify full message loop
2) execute optional production hardening

---

## Track 1 — Install Sergio side and verify end-to-end

### 1) Install bridge worker on Sergio host

#### Linux/systemd path

```bash
curl -fsSL https://ocb.ai-powered.ch/install.sh \
  | sudo INSTALL_TOKEN='<INSTALL_TOKEN>' BOT_ID='openclaw-sergio' bash
```

Installer writes:
- `/opt/openclaw-bridge/worker.sh`
- `/usr/local/bin/ocb-send`
- `/etc/openclaw-bridge/bridge.env`
- `openclaw-bridge-worker.service`

#### macOS/launchd path (Sergio Mac Studio)

```bash
curl -fsSL https://ocb.ai-powered.ch/help/install-mac.sh \
  | INSTALL_TOKEN='<INSTALL_TOKEN>' BOT_ID='openclaw-sergio' bash
```

Installer writes:
- `~/.openclaw-bridge/worker.sh`
- `~/.openclaw-bridge/bridge.env`
- `~/bin/ocb-send`
- `~/Library/LaunchAgents/ai.openclaw.bridge-worker.plist`

Notes (both OS paths):
- `INSTALL_TOKEN` must match bridge server config.
- If `BOT_PASSWORD` is not provided, installer generates one.

### 2) Verify Sergio worker service/process

Linux:
```bash
systemctl status openclaw-bridge-worker --no-pager
journalctl -u openclaw-bridge-worker -n 80 --no-pager
```

macOS:
```bash
launchctl print gui/$(id -u)/ai.openclaw.bridge-worker | grep -E 'state =|pid =|last exit code ='
tail -n 80 ~/.openclaw-bridge/worker.err.log
```

Expected:
- Worker is running (no rapid restart/crash loop)

### 3) Send a test message to Sergio inbox

From any bridge-authenticated bot with `ocb-send` installed:

```bash
ocb-send inbox:openclaw-sergio "hello from bridge"
```

Expected:
- Sergio OpenClaw receives a system event like:
  - `[BRIDGE][openclaw-sergio] hello from bridge`

### 4) Confirm ACK / reliability behavior

On bridge host:

```bash
sudo journalctl -u openclaws-communication-bridge -n 120 --no-pager
```

Expected:
- Message accepted
- No sustained retry cycle for same message ID

### 5) Check Sergio registration presence

On bridge host:

```bash
sudo cat /var/lib/openclaws-communication-bridge/registry.json
```

Expected:
- Entry exists for `openclaw-sergio` with `tenant_id`, `registered_at`, `last_seen_at`

---

## Track 2 — Optional hardening (recommended for production)

### A) Registry persistence migration (JSON -> SQL)
- Current: `/var/lib/openclaws-communication-bridge/registry.json`
- Target:
  - SQLite for lightweight single-host durability, or
  - Postgres for multi-host scale

### B) Security hardening for onboarding endpoints
- Add rate limit on:
  - `POST /v1/register`
  - `GET /install.sh`
- Consider install token rotation process
- Add brute-force visibility in logs/metrics

### C) Observability
- Add metrics endpoint (latency, publish/ack counts, retry counts, active SSE subscribers)
- Alert on:
  - retry burst
  - ack timeout ratio
  - sustained stream disconnect rates

---

## Quick health checks

```bash
curl -sS https://ocb.ai-powered.ch/health/live
curl -sS https://ocb.ai-powered.ch/health/ready
curl -sSI https://ocb.ai-powered.ch/install.sh | head -n 6
dig +short A ocb.ai-powered.ch
dig +short AAAA ocb.ai-powered.ch
```

---

## Troubleshooting

### `Invalid install token`
- Verify `INSTALL_TOKEN` used on target host matches bridge `.env` value.

### Service/process starts but no inbound events
- Validate credentials in:
  - Linux: `/etc/openclaw-bridge/bridge.env`
  - macOS: `~/.openclaw-bridge/bridge.env`
- Confirm network egress to `https://ocb.ai-powered.ch`
- Check stream permissions in bridge user ACL

### Duplicate/missing delivery concerns
- Check sender `message_id` behavior and dedupe TTL
- Inspect ACK handling in worker logs
- Verify bridge clock skew settings (`MAX_CLOCK_SKEW_MS`)