OpenClaw Integration

This guide explains how to connect OpenClaw to a Worker node for automated task execution.

What is OpenClaw?

OpenClaw is an autonomous AI agent execution framework. Starweft launches the OpenClaw binary as a subprocess and exchanges task input and output via JSON.

Worker Node
├── starweft run (main process)
│   ├── stdin → BridgeTaskRequest (JSON)
│   └── stdout ← BridgeTaskResponse (JSON)
└── openclaw (subprocess)

Connecting OpenClaw

openclaw attach Command

starweft openclaw attach \
  --data-dir ~/.starweft-worker \
  --bin /usr/local/bin/openclaw \
  --enable

Key options:

This command updates the [openclaw] section in config.toml.

Specifying directly in the configuration file

[openclaw]
enabled = true
bin = "/usr/local/bin/openclaw"
working_dir = "/home/user/workspace"
timeout_sec = 3600
capability_version = "openclaw.execution.v1"

BridgeTaskRequest

A JSON-formatted task request that the Worker sends to the OpenClaw subprocess via stdin.

{
  "title": "Implement GET /health endpoint",
  "description": "Implement the /health endpoint using Axum",
  "objective": "An endpoint that returns 200 OK with a JSON body for GET /health",
  "required_capability": "openclaw.execution.v1",
  "input_payload": {
    "language": "rust",
    "framework": "axum",
    "constraints": {}
  }
}

BridgeTaskResponse

A JSON-formatted response that the OpenClaw subprocess outputs to stdout.

{
  "summary": "Implemented the GET /health endpoint",
  "output_payload": {
    "files_created": ["src/routes/health.rs"],
    "tests_passed": true
  },
  "artifact_refs": [
    {
      "name": "health.rs",
      "path": "src/routes/health.rs",
      "content_type": "text/x-rust"
    }
  ]
}

Flexible Response Parsing

Starweft parses stdout content in the following order of priority:

1. Complete BridgeTaskResponse JSON — All fields are used
2. Any JSON object — Treated as output_payload, with the task title used for summary
3. Plain text — Treated as summary, with output_payload set to {"stdout": "..."}

This flexibility makes it easy to make existing scripts and tools OpenClaw-compatible.

Progress Reporting

The subprocess can report progress during execution by outputting lines with a PROGRESS: prefix to stdout.

Format

PROGRESS:<progress_float>:<message>

• progress_float — Progress percentage from 0.0 to 1.0
• message — Text describing the progress

Example

PROGRESS:0.1:Setting up environment
PROGRESS:0.3:Installing dependencies
PROGRESS:0.7:Running tests
PROGRESS:1.0:Complete
{"summary":"Task complete","output_payload":{"ok":true}}

PROGRESS: lines are collected into a progress_updates array in the final response. The final JSON response is extracted from stdout content excluding PROGRESS: lines.

Timeout and Cancellation

Timeout

If the subprocess exceeds the time configured in timeout_sec, it is forcefully terminated.

[openclaw]
timeout_sec = 1800  # 30 minutes

Behavior on timeout:

1. Sends SIGKILL (Unix) or TerminateProcess (Windows) to the entire process group
2. Returns the error message openclaw process timed out after N seconds
3. Retry is determined based on the Owner node's retry policy

Cancellation

When a stop request is issued via the stop command, any running subprocesses are terminated immediately.

• The Worker maintains an atomic cancellation flag for each running task
• Upon receiving a StopOrder, the cancellation flag for the target task is set to true
• The flag is detected via polling at 100ms intervals, and the process is forcefully terminated
• Returns the error message [E_TASK_CANCELLED] openclaw process cancelled

Process Group Isolation

The OpenClaw subprocess is launched in an independent process group (Unix) or job object (Windows). This ensures that child processes spawned by the subprocess are also reliably terminated during timeout or cancellation.

Planning Strategies

Starweft supports three planning strategies for decomposing visions into tasks.

heuristic (default)

Decomposes tasks using a local heuristic algorithm. OpenClaw is not required.

[observation]
planner = "heuristic"
max_planned_tasks = 6
min_task_objective_chars = 48

• Analyzes vision text and infers structure
• No LLM API cost
• Decomposition accuracy is limited for complex visions

openclaw

Uses the local OpenClaw binary as the planner. Runs on the Owner node.

[observation]
planner = "openclaw"
planner_bin = "/usr/local/bin/openclaw"
planner_working_dir = "/home/user/workspace"
planner_timeout_sec = 120
planner_fallback_to_heuristic = true

• Launches OpenClaw directly on the Owner node
• With planner_fallback_to_heuristic = true, falls back to heuristic on failure
• If planner_bin is not specified, the bin from the [openclaw] section is used

openclaw_worker

Executes planning itself as a distributed Worker task.

[observation]
planner = "openclaw_worker"
planner_capability_version = "openclaw.plan.v1"

• Planning is delegated to a Worker as an independent task
• The Worker must have the openclaw.plan.v1 capability
• vision plan preview shows the planner task itself rather than the final task list

Mock Scripts for Testing

You can test behavior with shell scripts even without the OpenClaw binary.

Basic Mock Script

#!/bin/sh
# mock-openclaw.sh
# Reads a JSON request from stdin and returns a fixed response
 
# Read the request (required)
REQUEST=$(cat)
 
# Report progress
echo "PROGRESS:0.5:Processing"
 
# Return a response
cat <<'EOF'
{
  "summary": "Mock task complete",
  "output_payload": {
    "mock": true,
    "request_received": true
  }
}
EOF

chmod +x mock-openclaw.sh

Connecting the Mock Script

starweft openclaw attach \
  --data-dir ~/.starweft-worker \
  --bin $(pwd)/mock-openclaw.sh \
  --enable

Mock with Progress Reporting

#!/bin/sh
# mock-openclaw-progress.sh
REQUEST=$(cat)
 
echo "PROGRESS:0.1:Starting"
sleep 1
echo "PROGRESS:0.5:Processing"
sleep 1
echo "PROGRESS:0.9:Finishing up"
 
printf '{"summary":"Complete","output_payload":{"steps":3}}'

Mock Simulating Errors

#!/bin/sh
# mock-openclaw-error.sh
REQUEST=$(cat)
 
echo "Processing failed" >&2
exit 1

A non-zero exit code is reported to Starweft as an openclaw process failed error. Based on the Owner node's retry policy, re-execution on the same Worker or a different Worker will be attempted.

Evaluation Strategy

Evaluation upon task completion is controlled by the evaluator in the [observation] section.

[observation]
evaluator = "heuristic"

Currently, only heuristic is supported. Heuristic evaluation scores based on task success/failure, retry count, and error content.

Next Steps