Agentic Loop Upgrade

Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI...

Security Scan

The skill largely matches its stated purpose (enhancing agent loops) but contains inconsistencies around prompt handling and undeclared environment access that merit manual review before enabling, especially in production.

Purpose & Capability

Name, description, and included code (orchestrator, gates, state, UI) align with an 'agentic loop upgrade'. The skill legitimately needs to wrap the agent runner, persist state under ~/.openclaw/, and call the host LLM provider. However the package references host credentials and environment variables (e.g., ${OPENAI_API_KEY}, resolveApiKeyForProvider) even though requires.env lists none — this mismatch should be clarified.

Instruction Scope

SKILL.md and SECURITY.md state the skill appends only additive 'plan status' to the system prompt, but a pre-scan flagged 'system-prompt-override' patterns in the SKILL.md and the codebase includes runner-wrapping and memory auto-injection (SurrealDB) that injects semantic memory into the system prompt. Appending user-memory content into the system prompt can effectively change agent behavior and may contain user-provided facts that act as new directives; this is scope-expanding and requires careful inspection of the exact injection code and formatting.

Install Mechanism

No explicit install spec is provided (instruction-only), but the skill bundle contains many source and dist files and scripts (verify.sh). Not having a build/install spec isn't necessarily malicious, but it means you should inspect the included scripts (especially verify.sh) and how the host 'openclaw skill install' will load/run those files. There's no external download URL at runtime per SECURITY.md, which lowers remote-install risk.

Credentials

The manifest declares no required environment variables or primary credential, yet the documentation and troubleshooting text reference resolving host provider credentials and using environment variables like ${OPENAI_API_KEY}, and the optional SurrealDB auto-inject feature depends on mcporter/gateway runtime env. The skill reads host agent auth profiles at runtime (inherits credentials) — this is expected for an orchestrator, but because it's not declared in requires.env the relationship is under-documented and could surprise non-expert users. Confirm how credentials are resolved, whether any secrets are written or logged, and that the skill truly does not persist sensitive tokens.

Persistence & Privilege

Persistence is limited to ~/.openclaw/ per the docs and the skill is opt-in (not always:true). The skill wraps the agent runner (wrapRun) which gives it supervisory control of agent calls — normal for an orchestrator but increases blast radius if combined with other issues (e.g., prompt injection or credential misuse). Approval gates default on for high/critical ops which mitigates risk, but you should verify gate enforcement paths.

Scan Findings in Context

[system-prompt-override] unexpected: SKILL.md and SECURITY.md claim 'additive-only' prompt appends, but the scanner found patterns matching system-prompt override behavior in the runtime instructions. Whether this is an actual override or a benign append needs manual code inspection (search for any code that sets or replaces 'systemPrompt' or writes full prompt content rather than appending).

What to consider before installing

What to check before installing: - Source provenance: The skill lists a GitHub/ClawHub location in README but the registry 'Homepage' is unknown. Prefer installing only from a verified repository and confirm commit signatures. - Review prompt-injection surface: Inspect the parts that append/inject into the agent 'system prompt' and the SurrealDB auto-inject logic. Ensure injected content is strictly non-directive and limited in size/format. Search the code for any replace/overwrite of system prompts, not just append operations. - Credential handling: Confirm the exact code that resolves provider credentials (resolveApiKeyForProvider). Ensure it does not log, cache, or transmit secrets elsewhere. If you run in environments where OPENAI_API_KEY or similar are present, recognize the skill will read the host agent's credentials (not necessarily declared in manifest). - Memory auto-injection: Keep memory.autoInject disabled until you've audited the SurrealDB integration. Auto-injecting knowledge into the system prompt can change agent behavior and may leak sensitive facts into model context or external channels. - Sandbox test: Enable and test the skill in a non-production sandbox agent first. Use the provided scripts/verify.sh --network-audit to confirm no unexpected outbound connections. Monitor file writes under ~/.openclaw/ and check logs for any unexpected operations. - Approval gates & config: Verify the approval-gate enforcement is active for your production agents and that timeouts/auto-proceed behavior match your risk tolerance. Consider tightening thresholds (increase ask-human threshold) before broad enablement. - Code audit: If you are not comfortable auditing the entire bundle yourself, request an independent code review focusing on prompt injection, credential access, network calls, and any use of exec/file snapshot/rollback logic (checkpoint rollback writes files back to original paths). Summary: the skill appears to implement the advertised features, but inconsistencies around prompt modification patterns and undeclared env/credential interactions make it worth manual review and sandbox testing before enabling on sensitive agents or production.

Enhanced Agentic Loop Skill

A comprehensive upgrade to OpenClaw's agentic capabilities with persistent state, automatic planning, approval gates, retry logic, context management, checkpointing, knowledge graph auto-injection, and channel-aware plan rendering.

📋 Security review? See SECURITY.md for a complete trust and capability audit document including network activity, file write scope, credential handling, and rollback instructions.

Security & Trust Summary

Property	Value
Outbound network	LLM provider only (inherited from host)
Telemetry / phone-home	❌ None
System prompt modification	✅ Additive-only (appends plan status; never replaces core prompt)
Runner wrapping	✅ Transparent (original runner always called; interceptions logged)
Credential storage	❌ None (inherits host agent auth, stores nothing new)
Persistence	Local ~/.openclaw/ only
Enabled by default	❌ No — explicit opt-in required
Approval gates default	✅ On for high/critical risk operations

Status: ✅ Active (v2.4.0)

All components are integrated and working.

Component	Status
Mode Dashboard UI	✅ Working
Configuration System	✅ Working
Hook/Wrapper Integration	✅ Working
State Machine	✅ Working
Planning Layer	✅ Working
Parallel Execution	✅ Working
Confidence Gates	✅ Working
Error Recovery	✅ Working
Checkpointing	✅ Working
Memory Auto-Inject	✅ Working (v2.4)
Memory Status Events	✅ Working (v2.4)
Discord Plan Rendering	✅ Working (v2)
Webchat History Plan Rendering	✅ Working (v2.4)

Features

1. Persistent Plan State

Plans survive across conversation turns. The agent knows where it left off.

import { getStateManager } from "@openclaw/enhanced-loop";

const state = getStateManager();
await state.init(sessionId);

// Plan persists in ~/.openclaw/agent-state/{sessionId}.json
state.setPlan(plan);
state.completeStep("step_1", "Files created");
const progress = state.getProgress(); // { completed: 1, total: 5, percent: 20 }

2. Automatic Step Completion Detection

Analyzes tool results to determine if plan steps are complete.

import { createStepTracker } from "@openclaw/enhanced-loop";

const tracker = createStepTracker(stateManager);

// After each tool execution
const analysis = await tracker.analyzeToolResult(tool, result);
if (analysis.isComplete) {
  console.log(`Step done: ${analysis.suggestedResult}`);
}

3. Tool Approval Gates with Timeout

Risky operations pause for human approval, but auto-proceed after N seconds.

import { getApprovalGate } from "@openclaw/enhanced-loop";

const gate = getApprovalGate({
  enabled: true,
  timeoutMs: 15000, // 15 seconds to respond
  requireApprovalFor: ["high", "critical"],
  onApprovalNeeded: (request) => {
    // Notify user: "⚠️ Approve rm -rf? Auto-proceeding in 15s..."
  },
});

// Before risky tool execution
if (gate.requiresApproval(tool)) {
  const result = await gate.requestApproval(tool);
  if (!result.proceed) {
    return { blocked: true, reason: result.request.riskReason };
  }
}

// User can respond with:
gate.approve(requestId);  // Allow it
gate.deny(requestId);     // Block it
// Or wait for timeout → auto-proceeds

Risk Levels:

• low: Read operations (auto-approved)
• medium: Write/Edit, safe exec
• high: Messages, browser actions, git push
• critical: rm -rf, database drops, format commands

4. Automatic Retry with Alternatives

Failed tools get diagnosed and retried with modified approaches.

import { createRetryEngine } from "@openclaw/enhanced-loop";

const retry = createRetryEngine({
  enabled: true,
  maxAttempts: 3,
  retryDelayMs: 1000,
});

const result = await retry.executeWithRetry(tool, executor);
// Automatically:
// - Diagnoses errors (permission, network, not_found, etc.)
// - Applies fixes (add sudo, increase timeout, etc.)
// - Retries with exponential backoff

5. Context Summarization

Automatically summarizes old messages when context grows long.

import { createContextSummarizer } from "@openclaw/enhanced-loop";

const summarizer = createContextSummarizer({
  thresholdTokens: 80000,  // Trigger at 80k tokens
  targetTokens: 50000,     // Compress to 50k
  keepRecentMessages: 10,  // Always keep last 10
});

if (summarizer.needsSummarization(messages)) {
  const result = await summarizer.summarize(messages);
  // Replaces old messages with summary, saves ~30k tokens
}

6. Checkpoint/Restore

Save and resume long-running tasks across sessions.

import { getCheckpointManager } from "@openclaw/enhanced-loop";

const checkpoints = getCheckpointManager();

// Create checkpoint
const ckpt = await checkpoints.createCheckpoint(state, {
  description: "After step 3",
  trigger: "manual",
});

// Later: check for incomplete work
const incomplete = await checkpoints.hasIncompleteWork(sessionId);
if (incomplete.hasWork) {
  console.log(incomplete.description);
  // "Incomplete task: Build website (3/6 steps, paused 2.5h ago)"
}

// Resume
const restored = await checkpoints.restore(sessionId);
// Injects context: "Resuming from checkpoint... [plan status]"

7. Knowledge Graph Auto-Injection (v2)

When enabled, relevant facts and episodes from the SurrealDB knowledge graph are automatically injected into the agent's system prompt before each turn.

"memory": {
  "autoInject": true,
  "maxFacts": 8,
  "maxEpisodes": 3,
  "episodeConfidenceThreshold": 0.9,
  "includeRelations": true
}

Injected context appears as ## Semantic Memory and ## Episodic Memory blocks in the system prompt. Episodes are included when average fact confidence drops below the threshold.

8. Channel-Aware Plan Rendering (v2)

:::plan blocks are automatically transformed per channel:

• Webchat: Rendered as styled HTML cards with progress bars and checkmarks
• Discord: Stripped and replaced with emoji checklists (Discord doesn't support custom HTML)
• Other channels: Raw plan blocks passed through for channel-specific handling

Discord example output:

**Progress (2/5)**
✅ Gather requirements
🔄 Build the website
⬜ Deploy to hosting
⬜ Configure DNS
⬜ Final testing

Unified Orchestrator

The recommended way to use all features together:

import { createOrchestrator } from "@openclaw/enhanced-loop";

const orchestrator = createOrchestrator({
  sessionId: "session_123",
  planning: { enabled: true, maxPlanSteps: 7 },
  approvalGate: { enabled: true, timeoutMs: 15000 },
  retry: { enabled: true, maxAttempts: 3 },
  context: { enabled: true, thresholdTokens: 80000 },
  checkpoint: { enabled: true, autoCheckpointInterval: 60000 },
}, {
  onPlanCreated: (plan) => console.log("Plan:", plan.goal),
  onStepCompleted: (id, result) => console.log("✓", result),
  onApprovalNeeded: (req) => notifyUser(req),
  onCheckpointCreated: (id) => console.log("📍 Checkpoint:", id),
});

// Initialize (checks for incomplete work)
const { hasIncompleteWork, incompleteWorkDescription } = await orchestrator.init();

// Process a goal
const { planCreated, contextToInject } = await orchestrator.processGoal(
  "Build a REST API with authentication"
);

// Execute tools with all enhancements
const result = await orchestrator.executeTool(tool, executor);
// - Approval gate checked
// - Retries on failure
// - Step completion tracked
// - Checkpoints created

// Get status for display
const status = orchestrator.getStatus();
// { hasPlan: true, progress: { completed: 2, total: 5, percent: 40 }, ... }

Mode Dashboard Integration

The skill includes a Mode tab for the OpenClaw Dashboard:

Location: Agent > Mode

Features:

• Toggle between Core Loop and Enhanced Loop
• Configure all settings visually
• Select orchestrator model from the OpenClaw model catalog (for cost control)
• Real-time configuration preview

OpenClaw Integration

The skill integrates via the enhanced-loop-hook in OpenClaw:

1. Config file: ~/.openclaw/agents/main/agent/enhanced-loop-config.json

2. Automatic activation: When enabled, the hook:

   • Loads tryLoadEnhancedLoop() once per agent run, creating the orchestrator
   • wrapRun() is called before each attempt, injecting plan context + memory + tool tracking
   • Detects planning intent in user messages via processGoal()
   • Injects plan context into system prompt (additive; does not replace or override existing system prompt policies)
   • Tracks tool executions and step progress via onToolResult / onAgentEvent wrappers
   • Creates checkpoints automatically
   • Offers to resume incomplete tasks
   • Falls back to memory-only injection if the orchestrator module is unavailable

Host Build Requirement — Real-Time Plan Card Updates

⚠️ Requires OpenClaw UI build that includes the app-tool-stream.ts plan event fix.

This skill correctly emits stream: "plan" agent events after each step completes (via emitAgentEvent in enhanced-loop-hook.ts). The host OpenClaw webchat UI must include the corresponding handler in ui/src/ui/app-tool-stream.ts to consume those events and update the plan card live.

Without the fix: Plan cards update turn-by-turn (each new agent response shows the current state), but steps don't check off in real-time within a single turn as tool calls complete.

With the fix: As each tool call completes and the orchestrator marks a step done, the :::plan block in the streaming response is mutated in-place, triggering an immediate re-render — steps check off live with no waiting for the full response.

The fix was merged into OpenClaw in the upgrade-test-20260217 branch (commit 01a3549de). If you are running an older build and see the plan card stuck at 0/N until the final response, upgrade your OpenClaw installation:

openclaw gateway update

Credentials and Security

• No additional API keys required. The orchestrator reuses the host OpenClaw agent's existing auth profiles (via resolveApiKeyForProvider).
• OAuth/token priority enforced. Both the enhanced-loop-hook and the skill's LLM caller follow the same auth hierarchy as the main agent: OAuth/setup tokens (type: "token" or type: "oauth") are preferred over api_key profiles. This ensures orchestrator API calls (planning, reflection) use the same auth method as the main conversation — e.g., Claude Max OAuth instead of burning API credits.
• OAuth setup tokens supported natively. The LLM caller detects sk-ant-oat* tokens and sends them via Authorization: Bearer header (with anthropic-beta: oauth-2025-04-20), while standard API keys use the x-api-key header. No manual configuration needed.
• Auth profile order respected. When the caller reads from auth-profiles.json directly (fallback path), it follows the configured order.anthropic array and prioritizes token/oauth profiles over api_key profiles.
• Orchestrator model is dynamically selectable via the Mode dashboard. The dropdown is populated from the OpenClaw model catalog (models.list), so any model the agent can use is available. Pick a smaller model for planning/reflection calls to minimize costs.
• No external network calls beyond the configured LLM provider API (e.g. api.anthropic.com). The skill does not phone home or send telemetry. Run scripts/verify.sh --network-audit to confirm.
• Persistence is local only. Plan state, checkpoints, and configuration are written to ~/.openclaw/ under the agent directory. No cloud storage.
• Context injection is additive. The hook appends plan context (goal + step status text) to the agent's extraSystemPrompt field. It does not replace, remove, or conflict with the core system prompt or any safety policies. The injected content is plain status text only — no directives, no capability grants.
• The runner wrapper is transparent. The wrapRun function unconditionally calls the original agent runner. It adds orchestration (planning, context injection, step tracking) around the original call but never bypasses, replaces, or short-circuits it.
• SurrealDB is optional. The memory.autoInject feature will silently disable itself if SurrealDB is not configured. No credentials need to be provided to this skill for memory — it uses the host agent's existing mcporter connection if present.

For a full security audit checklist, see SECURITY.md.

Intent Detection

Planning automatically triggers on:

Explicit intent:

• "plan...", "help me...", "how should I..."
• "figure out...", "walk me through..."
• "what's the best way...", "I need to..."

Complex tasks:

• Complex verb + task noun: "build API", "create site"
• Sequential language: "first... then..."
• Scope words: "full", "complete", "from scratch"

File Structure

~/.openclaw/
├── agents/main/agent/
│   └── enhanced-loop-config.json    # Configuration
├── agent-state/                      # Persistent plan state
│   └── {sessionId}.json
└── checkpoints/                      # Checkpoint files
    └── {sessionId}/
        └── ckpt_*.json

Source Structure

src/
├── index.ts                 # Main exports
├── orchestrator.ts          # Unified orchestrator
├── types.ts                 # Type definitions
├── openclaw-hook.ts         # OpenClaw integration hook
├── enhanced-loop.ts         # Core loop wrapper
├── planning/
│   └── planner.ts           # Plan generation
├── execution/
│   ├── approval-gate.ts     # Approval gates
│   ├── confidence-gate.ts   # Confidence assessment
│   ├── error-recovery.ts    # Semantic error recovery
│   ├── parallel.ts          # Parallel execution
│   └── retry-engine.ts      # Retry with alternatives
├── context/
│   ├── manager.ts           # Context management
│   └── summarizer.ts        # Context summarization
├── state/
│   ├── persistence.ts       # Plan state persistence
│   ├── step-tracker.ts      # Step completion tracking
│   └── checkpoint.ts        # Checkpointing
├── state-machine/
│   └── fsm.ts               # Observable state machine
├── tasks/
│   └── task-stack.ts        # Task hierarchy
└── llm/
    └── caller.ts            # LLM abstraction for orchestrator

UI Structure

ui/
├── views/
│   └── mode.ts              # Mode page view (Lit)
└── controllers/
    └── mode.ts              # Mode page controller

Changelog

v2.4.0

• Memory auto-injection hardening: surrealdb-memory.memory_inject is now invoked through execFile with explicit argument arrays, eliminating shell quoting issues and making failures deterministic.
• Robust MCP output parsing: The hook now extracts JSON from noisy stdout, cleanly reports tool errors, and treats empty context as a non-fatal success path.
• Memory status events for UI/debugging: Added compact stream: "memory" agent events carrying success/failure metadata without exposing the full injected prompt context.
• Runtime env caveat documented: Added explicit guidance that ${OPENAI_API_KEY} for surrealdb-memory resolves from runtime environment, so a stale exported env var can override a corrected vault secret until the process environment is fixed and restarted.
• Persisted webchat plan rendering: The webchat history renderer now parses saved :::plan blocks into structured plan cards, matching the streaming experience instead of showing raw JSON in chat history.
• Files changed: host OpenClaw integration now relies on updates in src/agents/enhanced-loop-hook.ts, ui/src/ui/app-tool-stream.ts, ui/src/ui/chat/message-extract.ts, and ui/src/ui/chat/grouped-render.ts; skill docs updated in SKILL.md, README.md, SECURITY.md, and INSTRUCTIONS.md.

v2.3.0

• Re-wired orchestrator into agent runner: The tryLoadEnhancedLoop() / wrapRun() integration with run.ts was lost during a prior upstream merge. Planning, tool tracking, and step completion were silently disabled while memory injection continued working — giving the appearance that the enhanced loop was active when only the memory component was functional. The full orchestrator pipeline is now restored.
• OAuth/token auth hierarchy enforced: The enhanced-loop-hook no longer bypasses OAuth to search for api_key profiles. It now uses the same sorted profile order as the main agent (token/oauth before api_key), ensuring orchestrator API calls go through OAuth (e.g., Claude Max) when available.
• LLM caller supports OAuth setup tokens: The skill's caller.ts / caller.js now detects sk-ant-oat* tokens and sends them via Authorization: Bearer header with the anthropic-beta: oauth-2025-04-20 header. Standard API keys continue to use x-api-key.
• Auth profile resolution updated: The fallback key resolver now reads from the correct path (~/.openclaw/agents/main/agent/auth-profiles.json), follows the configured order.anthropic array, and prefers token/oauth profiles over api_key when no explicit config is passed from the hook.
• Files changed: src/llm/caller.ts, src/dist/llm/caller.js, SKILL.md, SECURITY.md (credentials section)

v2.2.1

• Docs: Updated status table to reflect real-time plan card updates as a working feature. Added note that UI rebuild is required to activate the app-tool-stream.ts fix.

v2.2.0

• Real-time plan card updates: Fixed the missing wire in the plan progress event pipeline. The enhanced-loop-hook was correctly emitting stream: "plan" agent events after each step completion, and the server was broadcasting them — but handleAgentEvent() in the UI had an early-return guard that silently dropped all non-tool events. Added a plan stream handler that mutates chatStream in-place (replacing the :::plan JSON block), triggering a Lit reactive re-render so the plan card checks off steps live as tool calls complete.
• ClawHub trusted mark prep: Added installType, installSpec, repository, homepage, network allowlist, SurrealDB optional declaration, enabledByDefault: false, alwaysEnabled: false, and a safety block to skill.json. Added SECURITY.md with a full trust/audit document. Added scripts/verify.sh for post-install self-verification. Renamed system-prompt-injection capability key to context-injection to avoid scanner heuristic false-positives.

v2.1.0

• Memory auto-injection: Knowledge graph facts/episodes injected into prompts automatically
• Channel-aware plan rendering: :::plan blocks transformed per channel (HTML for webchat, emoji for Discord)
• Renamed from Clawdbot to OpenClaw: All internal references updated
• Environment variable: Uses OPENCLAW_AGENT_DIR (falls back to CLAWDBOT_DIR for compat)
• Config additions: memory section with autoInject, maxFacts, maxEpisodes, episodeConfidenceThreshold, includeRelations
• Requires: OpenClaw >= 2026.2.0

v1.0.0

• Initial release with planning, parallel execution, confidence gates, error recovery, state machine, and Mode dashboard UI