什么是 智能体循环升级 (Agentic Loop Upgrade)？

智能体循环升级是一套全面的技术套件，旨在将标准的 AI 交互转变为复杂的、具备状态感知能力的流水线。通过将其集成到您的 Openclaw 技能库中，开发人员可以为智能体配备一个可观察的状态机，从而以高可靠性管理复杂的多轮任务。它专注于解决常见的智能体失效问题，提供跨对话轮次持久存在的计划，确保智能体在运行长时间操作时永远不会迷失进度。

该技能作为一个中间层，封装了核心智能体运行器，以提供如自动步骤完成检测和语义记忆注入等附加功能。它是为需要高信任环境的开发人员构建的，提供粒度化的工具审批门控和仅限本地的持久化，在保持数据主权的同时显著提升 Openclaw 技能的任务完成率。

下载入口:https://github.com/openclaw/skills/tree/main/skills/maverick-software/agent-mode-upgrades

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

智能体循环升级 (Agentic Loop Upgrade) 应用场景

• 执行复杂的、多阶段的软件开发工作流，这些流需要跨越数小时或多个会话跟踪进度。
• 通过自动审批门控管理高风险系统操作，对于数据库删除或文件删除等敏感命令暂停执行。
• 自动化长时间运行的研究或编码任务，从定期检查点和任务恢复中获益。
• 通过语义错误诊断和带有替代策略的智能重试逻辑，提高在不稳定环境中的智能体可靠性。

1. 编排器检测用户执行复杂任务的意图，并生成结构化的多步执行计划。
2. 初始化会话特定的状态管理器，将计划和当前进度持久化到本地 JSON 数据库中。
3. 在每次工具执行前，系统根据预定义的风险级别（低、中、高、关键）检查审批要求。
4. 步骤追踪器分析工具结果，自动确定计划阶段是否完成或是否需要重试。
5. 一旦达到 Token 阈值，通过摘要动态管理上下文，确保智能体保持高质量的工作记忆。
6. 实时计划状态被注入到系统提示词中，使智能体在整个生命周期内与原始目标保持一致。

智能体循环升级 (Agentic Loop Upgrade) 配置指南

要激活增强型智能体循环，请确保您的主机环境已更新并配置智能体特定设置。

# 确保您拥有用于实时计划渲染的最新 UI 修复程序
openclaw gateway update

配置通过位于智能体目录中的 enhanced-loop-config.json 文件进行管理：

# 配置路径
~/.openclaw/agents/main/agent/enhanced-loop-config.json

您还可以通过 OpenClaw 控制面板中的“智能体 > 模式”选项卡启用该技能并直观地调整参数。

智能体循环升级 (Agentic Loop Upgrade) 数据架构与分类体系

该技能在本地文件系统中组织其状态和配置，以确保隐私和速度。

name: agentic-loop-upgrade
description: "Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI for easy configuration."

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

Status: ? Active (v2.3.0)

All components are integrated and working.

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.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