openclaw-dev-harness

name

openclaw-dev-harness

description

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".

OpenClaw Dev Harness

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

Quick Start

# 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 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:

openclaw --dev gateway restart

Or run the gateway in foreground for live output:

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:

OPENCLAW_RAW_STREAM=1 openclaw --dev gateway --port 19001 --verbose

Test RPC methods directly:

openclaw --dev gateway call pluginId.action --params '{}'

Run Tests

For plugin unit tests (Vitest):

npx vitest run ~/.openclaw-dev/workspace/extensions/my-plugin/my-plugin.test.ts

For gateway-level validation:

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 for registration methods, config schema, and testing patterns
• Hook API details: See references/hooks-api.md for event types, handler signatures, and discovery
• Testing details: See 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