OpenCode Supervisor Plugin for OpenClaw

Autonomous task execution via OpenCode HTTP API with reliable verification through actual file changes.

What's New in v1.1.3

• Reliable error detection: Uses exit codes instead of text pattern matching
• Change verification: Confirms task completion via /session/:id/diff API
• No false positives: Doesn't mistake code containing "Error" for actual errors
• Progress tracking: Detects when model isn't making changes and prompts accordingly

Installation

openclaw plugins install openclaw-opencode-supervisor

Or install from GitHub:

openclaw plugins install github:zvenoai/openclaw-opencode-supervisor

Configuration

After installation, configure the plugin in your OpenClaw config:

openclaw config set plugins.openclaw-opencode-supervisor.enabled true
openclaw config set plugins.openclaw-opencode-supervisor.config.password "your-opencode-password"

Or edit ~/.openclaw/config.json:

{
  "plugins": {
    "openclaw-opencode-supervisor": {
      "enabled": true,
      "config": {
        "apiUrl": "http://127.0.0.1:4096",
        "username": "opencode",
        "password": "openclaw2026",
        "sandboxDir": "/root/clawd/sandbox",
        "credentialsDir": "/root/clawd/credentials",
        "maxIterations": 50,
        "timeoutMs": 180000
      }
    }
  }
}

Restart the gateway after configuration:

openclaw gateway restart

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | http://127.0.0.1:4096 | OpenCode HTTP API URL | | username | string | opencode | Basic auth username | | password | string | - | Basic auth password | | sandboxDir | string | /root/clawd/sandbox | Sandbox directory for code | | credentialsDir | string | /root/clawd/credentials | Credentials directory (read-only) | | maxIterations | integer | 50 | Max iterations before stopping | | timeoutMs | integer | 180000 | Timeout per API call (3 min) |

Usage

The plugin registers an opencode_task tool that the agent uses automatically when appropriate.

Example Prompts

"Create a Node.js project that connects to BCMS API"

"Refactor the Python scripts to use python-dotenv"

"Build a web scraper for product prices"

Direct Tool Usage

The agent can call the tool directly:

{
  "tool": "opencode_task",
  "params": {
    "task": "Refactor knowledge_factory.py to use .env and add type hints",
    "projectName": "knowledge-factory",
    "continueOnError": true
  }
}

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | task | string | yes | Detailed task description | | projectName | string | no | Project folder name in sandbox | | continueOnError | boolean | no | Auto-retry on errors (default: true) |

How It Works

1. Create Session     POST /session
         ↓
2. Send Task          POST /session/:id/message
         ↓
3. Check Response
   ├── Tool exit code ≠ 0? → Send fix prompt
   └── finish = "stop"?
         ↓
4. Verify Changes     GET /session/:id (summary.files > 0?)
   ├── files > 0 → ✅ Success
   └── files = 0 → Prompt to make changes
         ↓
5. Get Diff           GET /session/:id/diff
         ↓
6. Return Result with file changes summary

Reliable Indicators

The plugin uses only reliable indicators:

| Indicator | Source | Use | |-----------|--------|-----| | Exit code | tool.state.metadata.exit | Error detection (≠ 0 = error) | | File count | session.summary.files | Task completion verification | | Diff | /session/:id/diff | Actual changes made |

Not used (unreliable):

• Text pattern matching (e.g., /Error:/i)
• "TASK_COMPLETE" marker in model output

Task Status

| Status | Meaning | |--------|---------| | ✅ completed | Files changed, task done | | ⚠️ completed_no_changes | Model finished but no files changed | | ❌ failed | Tool errors (non-zero exit codes) | | ⏱️ max_iterations | Stopped after max attempts |

Requirements

• OpenClaw gateway running
• OpenCode server running (opencode serve --port 4096)
• Network access between OpenClaw and OpenCode

Verify Installation

# List installed plugins
openclaw plugins list

# Check plugin status
openclaw plugins info openclaw-opencode-supervisor

License

MIT