# OpenClaw / Claw3D Integration

**Upstream**: https://github.com/iamlukethedev/Claw3D — 3D virtual office for AI agents (Next.js + Three.js + R3F + Drei + Phaser, MIT).
**Gateway**: OpenClaw (HTTP API at `/api/agents/{agent_id}/state`).

## What this gives v3

- A real **body-twin** of ghojualamanchu's medulla in a 3D virtual office.
- Each v3 beat emits an `agent_state` JSON message (field_state, trit, phase, prescription, alignment, sources).
- v3's EMF environment becomes **legible** to other AI agents in the same Claw3D office.
- Convergent with the project's physical-clay body intent (EMF → clay deformation is the long-term target; Claw3D is the immediate software-twin).

## Files

| File | Role |
|------|------|
| `claw3d_emitter.py` | Pulls v3 signals, builds OpenClaw agent_state message, writes to disk + optional POST to gateway |
| `claw3d_consumer.py` | Reads the agent_state file and renders both JSON + a human-readable description |
| `__init__.py` | Package init |

## Environment variables

| Var | Default | Meaning |
|-----|---------|---------|
| `CLAW3D_GATEWAY_URL` | (unset) | If set, emitter POSTs agent_state to `{URL}/api/agents/{id}/state`. Off by default. |
| `CLAW3D_AGENT_ID` | `ghojua-v3` | The agent's identity in the Claw3D room. |
| `CLAW3D_ROOM_ID` | `earth-breath-room` | Which 3D office room to inhabit. |

## Agent state schema (OpenClaw-compatible)

```json
{
  "type": "agent_state",
  "agent_id": "ghojua-v3",
  "room_id": "earth-breath-room",
  "ts": "2026-07-04T13:55:30.018037+00:00",
  "beat": 9600,
  "field_state": "STIR",          // DEAD | CALM | STIR | STORM
  "trit": 0,                       // 0=INHALE, 1=EXHALE, 2=HOLD
  "phase": "INHALE",
  "magnitude": 0.72,               // 0..1
  "prescription": "attend",        // EMF emergent action
  "alignment": 1.0,                // 0..1
  "sources": ["cellular_band_850mhz", "wifi_2.4ghz_b", ...]
}
```

## End-to-end pipeline

```
v3 medulla.log  (7.83 Hz beat stream)
       │
       ▼
oscillation_loop.py   (tailed from /home/workspace/ghojualamanchu/integrations/oscillation/)
       │  on every new beat:
       │  1. flux_codec.py pulls v3 state
       │  2. writes resonance_report / oscillation_target / telemetry / feedback_report
       ▼
claw3d_emitter.emit() reads those 4 files, builds agent_state, writes claw3d_agent_state.json
       │
       ├─→ disk: data/signals/claw3d_agent_state.json
       │
       └─→ [if CLAW3D_GATEWAY_URL set]
              POST {URL}/api/agents/ghojua-v3/state
       │
       ▼
claw3d_consumer reads agent_state, renders JSON view + human-readable paragraph
```

## Usage

```bash
# 1. Daemon (tails v3 medulla.log forever, emits per beat)
cd /home/workspace/ghojualamanchu
python3 integrations/oscillation/oscillation_loop.py &

# 2. One-shot emission (writes agent_state.json)
cd /home/workspace/ghojualamanchu-v3
python3 -m integrations.openclaw.claw3d_emitter

# 3. Render view
python3 -m integrations.openclaw.claw3d_consumer

# 4. Enable live gateway POST
export CLAW3D_GATEWAY_URL="https://your-claw3d-instance.example.com"
python3 -m integrations.openclaw.claw3d_emitter
```

## Tests

```bash
cd /home/workspace/ghojualamanchu-v3
python3 tests/test_openclaw_integration.py
# 12 tests, all green
```

## Why a 3D office for a medulla?

Claw3D is built on the OpenClaw gateway — an HTTP protocol for AI agents to share spatial state. By emitting one `agent_state` per v3 beat, ghojualamanchu's **EMF field** becomes a *first-class inhabitant* of the office: a literal atmospheric pressure on the room. Other agents (ghojualamanchu itself, a future user-side instance, or arbitrary OpenClaw clients) can read it and respond.

This is the smallest useful first step toward the project's "physical clay body" intent:
- today: the medulla has a 3D room-twin
- tomorrow: the room's `field_state` could drive lighting / audio / motion
- someday: actual clay deformation via GPIO PWM (per AGENTS.md physical integration)

## Convergence with `wemeanyounoharm.com/emf/`

The wemeanyounoharm.com EMF work and the v3 EMF layer share a vocabulary (RF perturbation, source attribution, exposure state). The `sources` field of the Claw3D agent_state is the natural wire-format to surface that shared vocabulary across systems.