Tools
Goals
By Persistent, checkpointed goal-oriented task engine for OpenClaw. Set an objective, walk away, and it finishes — surviving restarts, crashes, and timeouts. Please leave your feedback!
Install
npm install &&Configuration Example
{
"plugins": {
"entries": {
"openclaw-goals": {
"enabled": true,
"config": {
"max_concurrent": 3,
"watchdog_interval_ms": 30000,
"stale_heartbeat_seconds": 120,
"default_max_steps": 200,
"max_retries": 3
}
}
}
}
}README
# 🦞 openclaw-goals
**Persistent, checkpointed goal-oriented task engine for OpenClaw.**
Set an objective, walk away, and the agent finishes it — surviving restarts, crashes, and timeouts. Native OpenClaw plugin, no external dependencies.
## Features
- **Persistent state** — goals survive gateway restarts, worker crashes, OOM kills
- **Checkpoint-aware workers** — sub-agents write progress after every step; resume exactly where they left off
- **Automatic recovery** — watchdog re-spawns crashed workers within 30 seconds
- **Step budgeting** — prevents runaway costs with configurable step limits
- **User notification** — alerts you when a goal needs input or completes
- **CLI + Agent tools** — manage goals from chat or terminal
## Quick Start
```bash
# Install from GitHub
openclaw plugins install git+https://github.com/MrDiamondBallz/openclaw-goals
# Or local dev
cd openclaw-goals
npm install && npm run build
openclaw plugins install .
```
After install, restart the gateway: `openclaw gateway restart`
## Usage
### Via agent chat
```
You: start a goal: refactor auth middleware to JWT
Agent: ✅ Goal started! Objective: refactor auth middleware to JWT
You: goal status
Agent: 🔄 goal-auth-refactor — active — 47/200 steps — 2h ago
You: goal pause
Agent: ⏸️ Paused at step 47.
You: goal resume
Agent: ▶️ Resumed from step 47.
```
### Via CLI
```bash
openclaw goal list
openclaw goal status <goal-id>
openclaw goal cancel <goal-id>
```
## Configuration
```json
{
"plugins": {
"entries": {
"openclaw-goals": {
"enabled": true,
"config": {
"max_concurrent": 3,
"watchdog_interval_ms": 30000,
"stale_heartbeat_seconds": 120,
"default_max_steps": 200,
"max_retries": 3
}
}
}
}
}
```
| Option | Default | Description |
|--------|---------|-------------|
| `max_concurrent` | 3 | Goals running at once |
| `watchdog_interval_ms` | 30000 | Health check frequency |
| `stale_heartbeat_seconds` | 120 | Worker declared dead after |
| `default_max_steps` | 200 | Step budget per goal |
| `max_retries` | 3 | Recovery attempts before failure |
## Architecture
```
openclaw-goals/
├── openclaw.plugin.json # Plugin manifest
├── package.json # npm package
├── SKILL.md # Agent usage docs (loaded by OpenClaw)
├── src/
│ ├── index.ts # Plugin entry — tools + commands + lifecycle
│ ├── manager.ts # Atomic state CRUD
│ ├── worker.ts # Sub-agent spawn + prompt builder
│ ├── watchdog.ts # Stale detection + recovery logic
│ └── types.ts # Goal state schema + config types
└── goals/ # State directory (created at runtime)
```
**Goal state** lives in `goals/goal-<id>.json` — atomic writes via temp+rename. No corruption.
**Worker** is an isolated sub-agent spawned via `api.runtime.subagent.run()` with a long timeout and the goal prompt.
**Watchdog** runs as an interval inside `gateway_start` → `gateway_stop` lifecycle hooks. It scans for stale heartbeats, re-spawns dead workers, and notifies on `awaiting_input`.
## For Developers
```bash
npm install
npm run build # compiles src/ → dist/
npm run clean # removes dist/
```
## How it compares
| Feature | Codex `/goal` | Claude Code | openclaw-goals |
|---------|:---:|:---:|:---:|
| Survives terminal close | ✅ | ❌ | ✅ |
| Survives gateway restart | ❌ | ❌ | ✅ |
| Background watchdog | ❌ | ❌ | ✅ |
| Native OpenClaw integration | ❌ | ❌ | ✅ |
| Step budgeting | ❌ | ❌ | ✅ |
| Pause/resume | ✅ | ✅ | ✅ |
| State persistence | file-based | memory | atomic JSON |
## Install from source
```bash
git clone https://github.com/MrDiamondBallz/openclaw-goals.git
cd openclaw-goals
npm install && npm run build
openclaw plugins install .
openclaw gateway restart
```
## License
MIT
tools
Comments
Sign in to leave a comment