Openclaw Local Web Bridge Integration

# OpenClaw Web Local Bridge Integration

Status: accepted  
Date: 2026-03-10  
Related: [openclaw-local-bridge-protocol-spec.md](./openclaw-local-bridge-protocol-spec.md), [openclaw-web-technical-architecture.md](./openclaw-web-technical-architecture.md), [../pi_agent_rust/docs/rpc.md](../pi_agent_rust/docs/rpc.md)

## 1. Purpose

Define the direct local communication contract between the web UI and the local `pi_agent_rust` bridge.

Goal:

- after the page loads, the browser should prefer localhost data
- cloud is used for linking, policy, persistence, and artifact coordination
- live session state and messages should come from the local bridge when available

This keeps the product local-first while preserving the web control plane as the durable management layer.

## 2. Authority Rule

Runtime and client behavior remain authoritative.

The web app may:

- probe localhost
- request a link challenge from the cloud control plane
- redeem that challenge through the local bridge
- read local session state and messages

The web app must not assume a local endpoint is valid unless the bridge actually serves it.

If client behavior and this document differ, the client wins and the web mapping layer must be updated.

## 3. Transport Model

### 3.1 Browser to local bridge

- transport: HTTP on `127.0.0.1:43115`
- browser reads local state directly from localhost
- no cloud round-trip is required for read-only local session hydration

### 3.2 Browser to cloud control plane

- HTTPS
- used for:
  - link challenge creation
  - workspace policy
  - system/task persistence
  - artifact/result coordination

### 3.3 Local bridge to runtime

- local JSONL RPC over stdio using `pi_agent_rust --mode rpc`

## 4. Endpoint Set

### 4.1 Health probe

The web app probes these in order:

1. `http://127.0.0.1:43115/healthz`
2. `http://127.0.0.1:43115/v1/healthz`
3. `http://127.0.0.1:43115/bridge/health`

Expected minimum response:

```json
{
  "ok": true,
  "connected": true,
  "deviceId": "optional",
  "sessionId": "optional",
  "runtimeReady": true
}
```

### 4.2 Link redeem

The web app redeems challenges against these in order:

1. `http://127.0.0.1:43115/link/redeem`
2. `http://127.0.0.1:43115/v1/link/redeem`

Request body:

```json
{
  "challengeId": "bridge_challenge_id",
  "code": "123456",
  "appUrl": "https://xinxiang.xin"
}
```

### 4.3 Local RPC proxy

The web app sends browser-local runtime reads to one of:

1. `http://127.0.0.1:43115/rpc`
2. `http://127.0.0.1:43115/v1/rpc`
3. `http://127.0.0.1:43115/bridge/rpc`

Request envelope:

```json
{
  "id": "web-get_state-uuid",
  "type": "get_state"
}
```

Supported read commands for the first web-local integration:

- `get_state`
- `get_messages`
- `get_session_stats`

The bridge should return the normal Pi RPC response envelope shape.

## 5. Trigger Mechanism

The trigger model is intentionally conservative so localhost is preferred without spamming the bridge.

### 5.1 Initial triggers

Run local probe on:

- page load
- home page mount
- chat page mount

### 5.2 Refresh triggers

Re-check localhost on:

- window focus
- document becomes visible again
- browser `online` event
- manual retry action
- send-message action
- stale session heartbeat or stale local state indicator

### 5.3 Cooldown

Recommended cooldown:

- focus: 3 seconds
- visibility: 3 seconds
- online: 1.5 seconds

The web app should debounce repeated browser events so a tab-switch burst does not create repeated localhost calls.

## 6. Page Behavior

### 6.1 Home page

On load:

1. detect host environment
2. probe localhost bridge
3. if local bridge is absent, show install path
4. if local bridge is present but not linked, request a cloud challenge and enable direct redeem
5. if local bridge is present and already linked, show direct-entry path into the console

### 6.2 Chat page

On load:

1. render server fallback view immediately
2. probe localhost bridge in the browser
3. if localhost is reachable:
   - call `get_state`
   - call `get_messages`
   - call `get_session_stats`
4. replace fallback chat content with local session data
5. continue refreshing on focus and visibility triggers

This is the preferred pattern for all live runtime surfaces.

### 6.3 Dashboard and operations pages

Dashboard, Sessions, and Agents may continue to use control-plane data as the durable source of truth, but they should progressively decorate with localhost state when present.

## 7. Communication Guarantees

To keep communication reliable:

- every RPC call must carry a unique `id`
- bridge responses must preserve normal Pi RPC command names
- bridge must set CORS to allow the web origin
- bridge must reject unknown origins unless explicitly allowed
- local reads must be short-timeout and fail open back to web fallback UI
- local bridge should expose a version field in health responses

Recommended CORS allowlist:

- `https://xinxiang.xin`
- `http://localhost:3000`
- development origins explicitly configured by the team

## 8. Failure and Fallback Rules

If localhost probe fails:

- do not block page render
- keep server-rendered fallback data visible
- show install or retry path where relevant

If local RPC reads fail after health succeeds:

- keep the bridge marked reachable
- downgrade only the live-data portion of the UI
- retry on the next refresh trigger

If link redeem fails:

- keep manual code visible
- offer retry without invalidating the page state

## 9. Security

- localhost bridge must not expose privileged write operations to arbitrary origins
- browser-local read operations should be origin-checked
- challenge redeem must be one-time and short-lived
- provider secrets must never be returned to the browser
- raw local filesystem browsing is out of scope for this phase

## 10. Web Implementation Mapping

Current web-side mapping:

- bridge config and probe logic: `src/lib/local-bridge.ts`
- home linking flow: `src/components/HomeHostMatchPanel.tsx`
- chat local-first hydration: `src/components/ChatWorkspace.tsx`
- cloud-issued challenge source: `src/app/api/bridge/public-link/route.ts`

## 11. Client Requirements

For `pi_agent_rust` or its local bridge to support this cleanly, it should provide:

1. health endpoint on one accepted localhost path
2. link redeem endpoint on one accepted localhost path
3. RPC HTTP proxy endpoint on one accepted localhost path
4. Pi RPC envelope compatibility for:
   - `get_state`
   - `get_messages`
   - `get_session_stats`
5. CORS allowlist for approved web origins

## 12. Non-goals

Not required in this phase:

- arbitrary local filesystem browsing
- full media upload synchronization to cloud
- websocket streaming from browser directly to localhost bridge
- remote shell relay from the public website

The first goal is simple and strict:

- page loads
- browser checks localhost
- local state is used immediately when available
- cloud remains the durable coordination layer