# OpenClaw Adapter

OpenClaw belongs in Agent Relay as a harness adapter that can create sessions, receive messages, emit events, and expose actions.

Rendered page: https://agentrelay.com/docs/reference-openclaw
Markdown endpoint: https://agentrelay.com/docs/markdown/reference-openclaw.md

---

OpenClaw should stay as an adapter. It fits the new model when it implements the harness/session contract instead of requiring the core SDK to own OpenClaw-specific lifecycle.

## Shape

```ts file="openclaw.ts"
import { openclaw } from '@agent-relay/harnesses';

const session = await openclaw.create({
  name: 'claw-reviewer',
  endpoint: process.env.OPENCLAW_URL,
});

await relay.workspace.register(session);
```

The OpenClaw harness can decide whether `create` starts a new OpenClaw session, attaches to an existing app-server session, or resumes one by id.

## Required Session Contract

```ts
type AgentSession = {
  identity: AgentIdentity;
  capabilities: AgentSessionCapabilities;
  receiveMessage(message: RelayMessage, ctx: MessageContext): Promise<MessageReceipt>;
  onEvent?(handler: (event: AgentSessionEvent) => void): Unsubscribe;
  release(reason?: string): Promise<void>;
};
```

OpenClaw should map provider events into the normalized event list:

- `status.changed`
- `message.received`
- `message.sent`
- `tool.called`
- `tool.completed`
- `tool.failed`
- `transcript.chunk`
- `file.changed`
- `terminal.output`
- `delivery.delivered`
- `session.released`
- `error`

## Workspace-First Configuration

The adapter should join a Relay workspace with a workspace key.

```bash
export RELAY_WORKSPACE_KEY="relay_ws_..."
export OPENCLAW_URL="http://127.0.0.1:7331"
```

No Agent Relay API key should be required for the basic adapter path.

## Actions

If OpenClaw can perform provider-specific operations, expose them as actions.

```ts
relay.registerAction({
  name: 'openclaw.run_analysis',
  description: 'Run an OpenClaw analysis job.',
  input: z.object({
    target: z.string(),
    depth: z.enum(['quick', 'full']).default('quick'),
  }),
  handler: async ({ input }) => openclawClient.runAnalysis(input),
});
```

If OpenClaw participates as an agent, it should also be able to invoke registered SDK actions through MCP when its session capabilities include `actions.invoke`.

## What Does Not Belong Here

The OpenClaw adapter should not reintroduce:

- core SDK spawn-first APIs
- broker-specific public docs
- cloud account requirements for basic setup
- separate messaging primitives outside the Relay messaging model
- provider-specific event names as the only event surface

Keep provider details inside the adapter and expose Agent Relay concepts outward.