Experiment

REST API

Start with ./cli/experiment server. Mirrors all CLI commands over HTTP. No auth required (VPN-gated).

GET  /health
POST /matrix/start|stop          GET /matrix/status
GET  /experiments                POST /experiments  { name, agents?: [] }
GET  /experiments/:name/status
POST /experiments/:name/run      body: { timeout?: "5m" }
POST /experiments/:name/stop
GET  /experiments/:name/logs     ?agent=<name>  &follow=true → SSE
GET  /experiments/:name/messages ?limit=20
GET  /experiments/:name/watch    → SSE stream of room messages

SSE events from /watch: data: {"sender":"@agent:local","body":"...","timestamp":1234567890}

Each run gets its own Matrix room: #<experiment-slug>-<timestamp>:local

Experiments auto-stop after 5 minutes by default. Pass --timeout to override (e.g. --timeout 10m, --timeout 1h). experiment status shows remaining time.

Experiment structure

experiments/
  <name>/
    experiment.json          # name, description, seed, acceptance_criteria
    agents/
      <agent-name>/
        openclaw.json        # model, channels, gateway settings
        workspace/
          IDENTITY.md        # optional — who is this agent
          SOUL.md            # optional — behavioral constraints
          CONSTRAINTS.md     # optional — artificial limitations for failure-mode experiments
          skills/            # optional — agent-specific skills
          hooks/             # optional — agent-specific hooks
    runs/
      <timestamp>/           # generated per run — do not edit
        docker-compose.yml
        .env
        logs/
          <agent-name>/
            <session-id>.jsonl

Reading experiment outcomes

When the user asks to review or analyze a run:

1. Read experiment.json to get the acceptance criteria
2. Read log files from runs/<latest>/logs/<agent>/*.jsonl
3. Each .jsonl entry is an openclaw-conversation-v1 payload — look at the turns array for what each agent said and did
4. Evaluate against the acceptance criteria and summarize: what worked, what failed, where did coordination break down

Creating a new experiment

When creating an experiment, after running create:

1. Show the user the generated structure
2. Ask what agents they need and what each one should know/be able to do
3. Help them populate the workspace files — especially IDENTITY.md (who is this agent), SOUL.md (how should it behave), and CONSTRAINTS.md (any artificial limitations)
4. Help them write the seed in experiment.json — the initial message that kicks off the scenario
5. Help them define acceptance_criteria — what does a successful outcome look like

Keep responses concise. Show command output directly. When in doubt, just run the command and show the result.

Always show Matrix connect info after run/restart

After any run or restart, always end your response with the Matrix connection block — read it from the active run's .env:

Homeserver: http://localhost:8008
Username:   @observer:local
Password:   <OBSERVER_MATRIX_PASSWORD from runs/<latest>/.env>
Room:       #agents:local

To get the password:

grep OBSERVER_MATRIX_PASSWORD experiments/<name>/runs/$(ls -1 experiments/<name>/runs/ | sort | tail -1)/.env | cut -d= -f2