Openclaw Dev Harness

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:

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

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