# OpenClaw as a Service Agent Guide

This API is designed so another agent can operate a hosted OpenClaw instance without touching the browser UI.

## Required inputs

- API root: `/api`
- Bearer key: `Authorization: Bearer YOUR_API_KEY`
- Optional preferred instance id: `OPENCLAW_INSTANCE_ID`

## Minimal bootstrap

1. Fetch `GET /api` and cache the advertised resource paths.
2. List instances with `GET /api/instances`.
3. If no suitable instance exists, try `POST /api/instances`.
4. Create or reuse a chat session.
5. Use chat, files, or terminal endpoints depending on the task.

## Suggested operating rules

- Prefer reusing an existing `ready` instance before creating a new one.
- Use `POST /chat` for one-shot requests and `POST /chat/stream` when incremental output matters.
- Use `GET /chat/messages?tail=true` or `GET /chat/events` to sync state after reconnects.
- Use `POST /terminal/exec` for bounded commands and `/terminal/ws` for interactive sessions.
- Use `/files/upload`, `/files/write`, and `/files/mkdir` to place project files into `/workspace`.
- Treat `403` on instance creation as an access problem and `503` as infrastructure or capacity pressure.

## Example commands

Create or redeem access-backed instance:

```bash
curl -X POST /api/instances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invite_code":"YOUR_INVITE_CODE_IF_NEEDED"}'
```

Send a chat message:

```bash
curl -X POST /api/instances/INSTANCE_ID/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Review /workspace and tell me what to do next."}'
```

Upload file content:

```bash
curl -X POST /api/instances/INSTANCE_ID/files/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetDir":"/workspace","fileName":"notes.txt","content":"hello"}'
```

Run terminal command:

```bash
curl -X POST /api/instances/INSTANCE_ID/terminal/exec \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"pwd","timeout_ms":5000}'
```

## Companion artifacts

- `/docs`
- `/llms.txt`
- `/llms-full.md`
- `/api/openapi.json`
- `/api/openapi.yaml`
- `/skills/openclaw-api-control/SKILL.md`

No raw Sandy IPs are required for normal usage.