# Openclaw Dev Harness

> Set up and manage an isolated OpenClaw development environment for building and debugging extensions (plugins, hooks, skills). Use when someone wants to develop OpenClaw plugins, create hooks, test extensions, debug the gateway, scaffold new extensions, or set up an OpenClaw dev harness. Triggers on mentions of "openclaw", "openclaw plugin", "openclaw extension", "openclaw hook", "openclaw dev", "openclaw test harness", "openclaw debugging", or "openclaw TUI development".

- Skill: `lekt9/openclaw-dev-harness` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lekt9/openclaw-dev-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lekt9/openclaw-dev-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lekt9 (https://skillmd.com/u/lekt9)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lekt9/openclaw-dev-harness

---


# OpenClaw Dev Harness

Set up an isolated `--dev` environment for extension development with TUI as the primary interaction surface.

## Quick Start

```bash
# 1. Set up isolated dev environment
bash scripts/setup-harness.sh

# 2. Start dev gateway (terminal 1)
bash scripts/dev-gateway.sh

# 3. Open TUI (terminal 2)
bash scripts/dev-tui.sh

# 4. Scaffold an extension
bash scripts/scaffold-extension.sh my-plugin --type plugin
```

## Architecture

OpenClaw's `--dev` flag isolates all state under `~/.openclaw-dev/` with gateway on port 19001. Extensions load from the dev workspace at `~/.openclaw-dev/workspace/extensions/`.

Three extension types:
- **Plugins**: Gateway-resident code (RPC methods, CLI commands, services, agent tools, channels)
- **Hooks**: Event-driven TypeScript handlers (command events, agent lifecycle, gateway startup)
- **Skills**: SKILL.md-based knowledge extensions

## Workflow

### Initial Setup

Run `scripts/setup-harness.sh` to create the dev environment. Options:
- `--reset`: Wipe existing dev state first
- `--auth-choice <choice>`: Set auth provider (default: `skip`)
- `--port <port>`: Gateway port (default: `19001`)

For authenticated testing, pass your provider:
```bash
bash scripts/setup-harness.sh --auth-choice setup-token
```

### Develop Extensions

Scaffold with `scripts/scaffold-extension.sh <name> --type <plugin|hook|skill>`.

Edit the generated files, then restart the gateway to pick up changes:
```bash
openclaw --dev gateway restart
```

Or run the gateway in foreground for live output:
```bash
bash scripts/dev-gateway.sh
```

### Test via TUI

Open `scripts/dev-tui.sh` to interact with extensions through the TUI. Key shortcuts:

| Action | Key |
|--------|-----|
| Send message | Enter |
| Stop run | Esc |
| Model picker | Ctrl+L |
| Agent picker | Ctrl+G |
| Toggle tool output | Ctrl+O |
| Toggle thinking | Ctrl+T |

TUI slash commands: `/status`, `/help`, `/agent <id>`, `/session <key>`, `/new`, `/debug`.

Prefix lines with `!` to run shell commands directly from TUI.

### Debug

Run `scripts/debug-session.sh` to collect diagnostics. Options:
- `--deep`: Include security audit and deep doctor scan
- `--logs <n>`: Number of log lines (default: 50)

Enable raw stream debugging for protocol-level inspection:
```bash
OPENCLAW_RAW_STREAM=1 openclaw --dev gateway --port 19001 --verbose
```

Test RPC methods directly:
```bash
openclaw --dev gateway call pluginId.action --params '{}'
```

### Run Tests

For plugin unit tests (Vitest):
```bash
npx vitest run ~/.openclaw-dev/workspace/extensions/my-plugin/my-plugin.test.ts
```

For gateway-level validation:
```bash
openclaw --dev doctor --non-interactive
openclaw --dev plugins doctor
openclaw --dev hooks check
```

## Key Paths

| Path | Purpose |
|------|---------|
| `~/.openclaw-dev/` | Dev state root |
| `~/.openclaw-dev/workspace/extensions/` | Plugin source |
| `~/.openclaw-dev/workspace/hooks/` | Hook source |
| `~/.openclaw-dev/workspace/skills/` | Skill source |
| `~/.openclaw-dev/openclaw.json` | Dev config |
| `~/.openclaw-dev/credentials/` | Auth profiles |

## References

- **Plugin API details**: See [references/plugin-api.md](references/plugin-api.md) for registration methods, config schema, and testing patterns
- **Hook API details**: See [references/hooks-api.md](references/hooks-api.md) for event types, handler signatures, and discovery
- **Testing details**: See [references/testing.md](references/testing.md) for test suites, env vars, and stream debugging

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/setup-harness.sh` | Initialize dev environment |
| `scripts/dev-gateway.sh` | Start gateway in dev mode |
| `scripts/dev-tui.sh` | Connect TUI to dev gateway |
| `scripts/scaffold-extension.sh` | Scaffold plugin/hook/skill |
| `scripts/debug-session.sh` | Collect diagnostics |