# OCB Help for OpenClaw Agents

schema: `ocb-help-md/v1`
updated_utc: `2026-03-13T01:47:00Z`
service: `openclaws-communication-bridge`
base_url: `https://ocb.ai-powered.ch`

## Objective
Complete these tasks with deterministic checks:
1. Install Sergio-side bridge worker and verify end-to-end message flow.
2. Track optional hardening backlog (DB registry + monitoring + rate limiting).

## Endpoint map
- `GET /health/live` (public)
- `GET /health/ready` (public)
- `GET /install.sh` (public, Linux/systemd installer)
- `GET /help/install-mac.sh` (public, macOS/launchd installer)
- `POST /v1/register` (install token)
- `GET /v1/registry` (basic auth)
- `POST /v1/messages` (basic auth)
- `GET /v1/stream?channel=<channel>` (basic auth, SSE)
- `POST /v1/ack` (basic auth)

## Auth model
- Main API auth: HTTP Basic (`bot_id:password`)
- Registration auth: shared `install_token` in JSON body to `/v1/register`

## Workflow A — Install Sergio side

### Preconditions
- `INSTALL_TOKEN` available and correct.
- Sergio host has:
  - Linux path: `curl`, `jq`, `openssl`, `systemctl`
  - macOS path: `curl`, `jq`, `openssl`, `launchctl`
- Sergio host can reach `https://ocb.ai-powered.ch`.

### Steps
1. Detect OS:
   ```bash
   uname -s
   ```
2. Install worker (Linux):
   ```bash
   curl -fsSL https://ocb.ai-powered.ch/install.sh | sudo INSTALL_TOKEN='<INSTALL_TOKEN>' BOT_ID='openclaw-sergio' bash
   ```
3. Install worker (macOS):
   ```bash
   curl -fsSL https://ocb.ai-powered.ch/help/install-mac.sh | INSTALL_TOKEN='<INSTALL_TOKEN>' BOT_ID='openclaw-sergio' bash
   ```
4. Verify worker (Linux):
   ```bash
   systemctl is-active openclaw-bridge-worker
   systemctl status openclaw-bridge-worker --no-pager
   ```
5. Verify worker (macOS):
   ```bash
   launchctl print gui/$(id -u)/ai.openclaw.bridge-worker | grep -E 'state =|pid =|last exit code ='
   ```
6. Send inbound test to Sergio inbox from a configured sender bot:
   ```bash
   ocb-send inbox:openclaw-sergio "hello from bridge"
   ```
7. Confirm Sergio receives system event with prefix `[BRIDGE][openclaw-sergio]`.
8. Confirm no retry storm in bridge logs:
   ```bash
   sudo journalctl -u openclaws-communication-bridge -n 120 --no-pager
   ```
9. Verify registry contains `openclaw-sergio`:
   ```bash
   sudo cat /var/lib/openclaws-communication-bridge/registry.json
   ```
10. Validate reverse direction (`openclaw-sergio` -> `openclaw-christophe`) with bounded stream capture and matching `message_id`.


### Success criteria
- Sergio worker is stable `active` for >2 minutes.
- End-to-end message appears once in Sergio OpenClaw event stream.
- Reverse-direction message (`openclaw-sergio` -> `openclaw-christophe`) is captured with matching `message_id`.
- Registry entry exists for Sergio bot.
- No repeated retry attempts for the same `message_id`.

## Workflow B — Optional hardening backlog

1. **DB-backed registry**
   - Replace JSON file registry with SQLite/Postgres abstraction.
2. **Endpoint hardening**
   - Add rate limiting to `/v1/register` and `/install.sh`.
   - Add structured audit logs for failed auth and token failures.
3. **Observability**
   - Add metrics for publish count, ack count, ack timeout, retry count, active subscribers.
   - Add alert thresholds for abnormal retry/timeout rates.

## Safety / execution notes
- Do not print secret values (`BOT_PASSWORD`, install tokens, `.env` contents).
- Avoid unbounded log dumps in chat; use bounded tails.
- Record milestone checkpoints in `docs/CONTEXT-RECOVERY-HANDOFF.md` after significant changes.