Autonomous agent platform for OpenClaw. A Claude Code-inspired framework for building AI agents that operate autonomously via Telegram with safety guardrails, quality gates, and interactive UX.
ZpokenClaw transforms an OpenClaw gateway into a full autonomous agent platform. It provides:
- Evaluator-Optimizer Loop — three-layer validation (structural checks, pattern matching, LLM-as-Judge) ensures agent outputs meet quality criteria before delivery
- Interactive Telegram UX — inline keyboard approvals, edit-in-place progress, slash commands, and progressive disclosure (inspired by Claude Code's UX patterns)
- Permission System — content-aware risk classification with autonomous-mode bypass, inline keyboard approval flow, and denial tracking with circuit breaker
- Priority Message Queue — incoming requests during active tasks are queued by priority (
now > next > later) with auto-pickup on completion - Parallel Worker Progress — track multiple concurrent sub-agents with compact tree-view progress display, edited in-place to avoid chat flooding
- Pipeline Execution — DAG-based multi-step workflows with checkpointing, conditions, routes, and reusable templates
- Daemon Bridge — reads infrastructure monitoring data from the OC12 daemon, exposing server health to the conversational agent
- Plugin Ecosystem — sandboxed execution, file management, Docker orchestration, git operations, web search, and self-extension
# One-command install (requires: Node.js 20+, OpenClaw gateway)
curl -fsSL https://raw.githubusercontent.com/ZpokenWeb3/ZpokenClaw/main/install.sh | bashOr manually:
git clone https://github.com/ZpokenWeb3/ZpokenClaw.git
cd ZpokenClaw
./install.shThe installer will:
- Detect your OpenClaw installation
- Copy plugins to
~/.openclaw/extensions/ - Register plugins in
openclaw.json - Run health checks via
doctor.sh - Restart the gateway
See ARCHITECTURE.md for the full technical design document, including:
- System diagram (gateway, daemon, Telegram, LLM providers)
- Implementation plan with 5 phases
- Validation report from 4 parallel verification agents
- Safety assessment and risk mitigations
┌──────────────────────────────────────────────┐
│ TELEGRAM USER │
└──────────────────┬───────────────────────────┘
│
┌──────────────────▼───────────────────────────┐
│ OPENCLAW GATEWAY (:18789) │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ ZPOKENCLAW EXTENSION │ │
│ │ │ │
│ │ Hooks: │ │
│ │ before-tool-call (permission gate) │ │
│ │ before-prompt-build (context inject) │ │
│ │ message-sending (progress edit) │ │
│ │ │ │
│ │ Services: │ │
│ │ daemon-bridge health-monitor │ │
│ │ message-queue progress-tracker │ │
│ │ denial-tracker │ │
│ │ │ │
│ │ Commands: │ │
│ │ /tasks /status /memory /queue │ │
│ │ /loop /stop /retry /skip /pipeline │ │
│ └───────────────────────────────────────┘ │
│ │
│ LLM ←→ Taskman ←→ SearXNG ←→ Tools │
└──────────────────────────────────────────────┘
│
▼ file bridge (read-only)
┌──────────────────────────────────────────────┐
│ OC12 DAEMON (cron/15min) │
│ Infrastructure monitoring, alerts, reports │
└──────────────────────────────────────────────┘
Each plugin is independently installable. Copy the plugin directory to ~/.openclaw/extensions/ and enable in openclaw.json.
| Plugin | Purpose | Key Features |
|---|---|---|
| zpokenclaw | Core agent platform | Eval loops, permission gates, message queue, progress tracking, slash commands, daemon bridge, inline keyboard approvals |
| exec | Sandboxed execution | Docker containers with configurable filesystem, network, resource limits |
| fs-tools | File operations | Read, write, edit, list, search with path security gates |
| docker-mgmt | Container management | ps, inspect, logs, run, start, stop, rm, pull |
| git-tools | Git operations | status, diff, log, add, commit, branch, checkout, push, pull (no force push) |
| web-search | Web search | SearXNG metasearch with quick/deep modes, phase-aware selection |
| service-registry | Service lifecycle | Health probes, dependency ordering, resource budgets, auto-restart |
| plugin-scaffold | Self-extension | Generate new plugins at runtime |
| Command | Description |
|---|---|
/status |
Combined system health: daemon cycles, service alerts, active tasks |
/tasks |
List active and recent tasks from task registry |
/memory [query] |
List or search workspace memory files |
/queue |
Show queued messages waiting for processing |
/loop |
Show current eval loop status, phase, criteria |
/stop |
Abort active eval loop and clear task state |
/retry |
Reset iteration count for current phase |
/skip |
Override eval gate for next delivery |
/pipeline |
Show pipeline execution status |
/queue clear |
Drain all queued messages |
ZpokenClaw implements a content-aware permission gate inspired by Claude Code's layered permission pipeline:
| Risk Tier | Tools | Behavior |
|---|---|---|
| safe | read_file, memory_search, exec (read-only commands like ls, cat, grep), web_search |
Always allowed |
| needs_ack | write_file, git_commit, git_push |
Soft gate (logged, future escalation) |
| blocked | rm -rf (non-tmp), DROP TABLE, shutdown, git push --force |
Requires explicit user approval via inline keyboard |
Autonomous mode bypass: Heartbeat, cron, and sub-agent sessions skip all permission gates to prevent deadlocks.
Denial tracking: After 3 consecutive denials or 15 total, the circuit breaker escalates to the user instead of silently blocking.
When the agent attempts a blocked operation:
Bot: ⚠️ Permission needed
exec: rm -rf /var/log/old/
[✅ Approve] [❌ Deny]
User clicks [Approve]
Bot: (proceeds with operation)
The two-phase flow:
before_tool_callblocks the operation, sends inline keyboard- User clicks button → callback dispatched as synthetic message
before_prompt_buildresolves the approval, injects context- Agent retries the operation, permission gate sees approval → allows
When a new task arrives during active work, ZpokenClaw queues it instead of dropping or conflating:
User: "Deploy the staging server" (while agent is analyzing code)
Bot: "Queued: 'Deploy the staging server'. Send /queue to see pending items."
(Agent completes current task)
Bot: "Picking up queued request: 'Deploy the staging server'..."
Three priority levels: now (bypass queue) > next (user requests) > later (system notifications). Messages expire after 30 minutes.
Edit-in-place progress messages prevent chat flooding:
Working on 2 subtasks (34s):
├─ ⏳ GitHub analysis (12 tools) — Scanning repos
└─ ✅ Server health (2s)
Synthesizing results...
Progress messages are edited in Telegram (not sent as new messages). Tracks tool use count, last activity description, and recent activity buffer.
The OC12 infrastructure monitoring daemon runs every 15 minutes via cron. ZpokenClaw bridges its data into the conversational agent:
- Reads
cycle_history.jsonlandSTATE.mdfrom the daemon's filesystem - Keyword-gated injection: only when user mentions "server", "health", "status", etc.
- Token-budgeted: max 500 tokens injected per turn
- Exposes via
/statuscommand for instant health checks
The daemon now supports telegram blocks — the LLM can produce ```telegram``` blocks that are sent as Telegram messages (previously silently dropped).
The daemon/ directory contains the autonomous infrastructure monitoring daemon:
- Cron-based: runs every 15 minutes
- 9 monitoring goals: infrastructure health, service registry, database health, security audit, problem resolution, daily reports, sub-tasks, self-testing, taskman health
- Telegram integration: sends daily reports, escalation alerts, and critical notifications
- Atomic writes: prevents torn reads from the gateway bridge
- Skills: extensible skill templates (see
daemon/skills/github_analytics.md)
# Check plugin health
./doctor.sh
# Run TypeScript checks (pre-existing errors from missing gateway types are expected)
cd plugins/zpokenclaw && npx tsc --noEmit
# Test commands via Telegram
# Send /status, /tasks, /memory to @ayopenclawdbotplugins/zpokenclaw/
├── index.ts # Plugin entry point
├── state.ts # Task state management
├── turn-state.ts # Per-turn state (progress, repetition, context)
├── eval-engine.ts # Three-layer evaluation engine
├── llm-judge.ts # LLM-as-Judge layer
├── approval-state.ts # Two-phase permission approval flow
├── task-registry.ts # Multi-task tracking with registry
├── memory-search.ts # Keyword-based memory file search
├── agent-types.ts # Role-specific sub-agent behavior
├── tool-registry.ts # Deferred tool discovery
├── data-verifier.ts # Mechanical data cross-validation
├── phase-checks.ts # Phase-specific structural checks
├── hooks/
│ ├── before-tool-call.ts # Permission gate + risk classification
│ ├── before-prompt-build.ts # Context injection, queue, approval resolution
│ ├── message-sending.ts # Edit-in-place progress, outbound gates
│ ├── after-tool-call.ts # Tool result processing
│ ├── session-lifecycle.ts # Session start/end handling
│ ├── llm-input.ts # Model capture for sub-agent injection
│ ├── subagent-ended.ts # Sub-agent result collection
│ ├── compaction-checkpoint.ts # Context compaction handling
│ └── tool-result-persist.ts # Tool result persistence
├── commands/
│ └── loop-commands.ts # /tasks, /status, /memory, /queue, /loop, etc.
├── services/
│ ├── daemon-bridge.ts # OC12 daemon state reader
│ ├── health-monitor.ts # Service health probing
│ ├── message-queue.ts # Priority message queue
│ ├── progress-tracker.ts # Multi-worker progress display
│ └── denial-tracker.ts # Permission denial circuit breaker
├── pipeline/
│ ├── pipeline-executor.ts # DAG-based pipeline execution
│ ├── pipeline-state.ts # Pipeline state persistence
│ ├── pipeline-types.ts # Pipeline type definitions
│ ├── pipeline-condition.ts # Conditional step execution
│ ├── pipeline-data.ts # Inter-step data passing
│ └── pipeline-templates.ts # Reusable workflow patterns
└── tools/
├── task-eval.ts # task_eval tool implementation
├── task-mgmt.ts # task_create, task_list, task_switch, task_clear
└── pipeline-tools.ts # pipeline_define, pipeline_status, etc.
ZpokenClaw's architecture draws heavily from Claude Code patterns:
| Pattern | Claude Code | ZpokenClaw |
|---|---|---|
| Permission pipeline | 10-step cascading evaluation with rules, classifier, mode transforms | Content-aware 3-tier gate with autonomous bypass and denial tracking |
| Progress tracking | ProgressTracker with tool counts, token tracking, recent activities | Edit-in-place Telegram messages with activity descriptions |
| Slash commands | Discriminated union (prompt/local/jsx) with lazy loading | Command registry with auth, args support, instant execution |
| Task queue | Priority-based unified command queue (now/next/later) | Message queue with TTL, priority levels, auto-drain on completion |
| Context management | Token-budget compaction with structured memory files | Keyword-gated injection with explicit token limits |
| Agent spawning | Nested query loops with coordinator mode | Taskman workers with parallel progress tracking |
MIT — see LICENSE.