EdgeClaw/README.md at main · OpenBMB/EdgeClaw

Secure · Cost-Effective · Efficient

Edge-Cloud Collaborative AI Agent
EdgeClaw: Bringing the Claude Code Experience to OpenClaw

【中文 | English】

👋 Join our community for discussion and support!

Feishu | Discord

What's New 🔥

[2026.04.03] 🚀 Three Claude Code-liked features released: 🔧 ClawXTool launches an 8-in-1 tool suite (including security analysis, secret scanning, git worktrees, etc.), 🔍 ClawXSkill releases an intelligent discovery engine (supporting skill search and model judge), and 🧠 ClawXContext introduces smooth context compaction and dynamic reinjection for long sessions.
[2026.04.02] 🚀 Released three Claude Code-liked features optimized for OpenClaw — 🤖 ClawXKairos (Self-Driven Agent Loop), 🛡️ ClawXGovernor (Tool Governance), and 📦 ClawXSandbox (Claude Code-Style Sandbox)
[2026.04.01] 🎉 EdgeClaw 2.0 is officially open-sourced, featuring a brand-new memory engine and cost-saving router — bringing the Claude Code experience to OpenClaw!
[2026.04.01] 🎉 ClawXMemory released — inspired by Claude Code's memory mechanism, it delivers a smoother experience for OpenClaw scenarios with multi-layered structured long-term memory and proactive reasoning!
[2026.03.25] 🎉 ClawXRouter released — 5-tier cost-saving routing + three-tier privacy collaboration + visual Dashboard
[2026.03.13] 🎉 EdgeClaw adds Cost-Aware Collaboration: automatically determines task complexity and matches the most economical cloud model
[2026.02.12] 🎉 EdgeClaw is officially open-sourced — an Edge-Cloud Collaborative AI Agent

💡 About EdgeClaw

EdgeClaw is an Edge-Cloud Collaborative AI Agent jointly developed by THUNLP (Tsinghua University), Renmin University of China, AI9Stars, ModelBest, and OpenBMB, built on top of OpenClaw.

OpenClaw vs Claude Code vs EdgeClaw

	OpenClaw	Claude Code	EdgeClaw
Cross-session project knowledge	✗	✓	✓
Persistent user preference	✗	✓	✓
Multi-layered structured memory	✗	✓	✓
Memory integration strategy	Recall	On-demand read	Proactive reasoning
Continuous memory consolidation	✗	Auto-Dream (backend)	Auto-consolidation on idle & topic switch
Cost-aware routing	✗	✗	58% cost savings
Three-tier privacy collaboration	✗	✗	S1/S2/S3
Context working set management	✗	✓	✓
Tool risk governance & audit	✗	✓	✓
Self-driven agent loop	✗	✓	✓
Sandboxed execution	✗	✓	✓
Intelligent skill discovery	✗	✗	✓
Built-in security tool suite	✗	△	✓
Virtual pet companion	✗	✓	✓
Visual Dashboard	✗	✗	✓

✨ Highlights at a Glance

🌟 Claude Code-Liked Features

🤖 Self-Driven Loop — ClawXKairos: Tick scheduling + Sleep tool + background command automation + async sub-agents, enabling the agent to work autonomously and continuously
🛡️ Tool Governance — ClawXGovernor: Three hook middlewares — context tail-window trimming, tool call risk interception & audit, session note incremental append. Deeply optimized for OpenClaw scenarios, saving 85% tokens over 30 rounds of calls
📦 Sandbox Execution — ClawXSandbox: Fully isolated local execution environment based on system-level sandboxing (bwrap / sandbox-exec). Focused on being lightweight, fast, and zero-dependency, completely eliminating all Docker overhead.
🔧 Unified Tool Suite — ClawXTool: 8-in-1 plugin providing 13 tools, covering security audit (bash security analysis, secret scanning), workflow (git worktree management, structured task tracking), development assistance (cron parsing, notebook editing), and agent interaction (memory age annotations, interactive user questions).
🔍 Skill Discovery — ClawXSkill: Automatically discovers and indexes agent skills across the workspace using BM25 keyword search, optional embedding-based semantic search, and LLM model judge for intelligent skill matching.
🧠 Memory Engine — ClawXMemory: A structured long-term memory engine built for OpenClaw. Building on the ideas behind Claude Code's memory mechanism, it further introduces multi-layered structured memory and model-driven memory retrieval. (v0.1.5)
📝 Context Engine — ClawXContext: OpenClaw context engine focused on long-session stability, smooth context compaction, and dynamic reinjection.
🐾 Virtual Pet Companion — ClawXBuddy: An adorable ASCII virtual pet companion with idle animations, rarity traits, and interactive commands to keep you company.

🔥 Other Core Features

💰 Cost-Saving Router — ClawXRouter: LLM-as-Judge automatically determines complexity, routing 60–80% of requests to cheaper models. Real-world PinchBench testing shows 58% cost savings with scores 6.3% higher.
🔒 Three-Tier Privacy — S1 direct cloud / S2 desensitized forwarding / S3 fully local processing — sensitive data never leaves the device.
🚀 Zero Configuration — pnpm build && node openclaw.mjs gateway run, auto-generates config on first launch, just fill in your API Key.
📊 Dual Dashboard — ClawXRouter routing config hot-reload + ClawXMemory memory canvas visualization.

🎬 Demo

EdgeClaw2_ZH_Demo.mp4

📦 Quick Start

1. Build

git clone https://github.com/openbmb/edgeclaw.git
cd edgeclaw

pnpm install
pnpm build

2. Launch

node openclaw.mjs gateway run

EdgeClaw uses ~/.edgeclaw/ as the data directory by default, completely isolated from OpenClaw (~/.openclaw/). To customize the path, set the OPENCLAW_STATE_DIR environment variable.

On first launch, a complete configuration skeleton is auto-generated (~/.edgeclaw/openclaw.json + clawxrouter.json), with ClawXRouter and ClawXMemory as bundled extensions — no manual plugin installation required.

3. Fill in API Key

The generated config has empty API Keys. Fill them in to get started:

Edit the config file: Modify the apiKey for each provider under models.providers in ~/.edgeclaw/openclaw.json
Dashboard hot-reload: Visit http://127.0.0.1:18790/plugins/clawxrouter/stats and modify directly in the UI — changes take effect immediately

Tip: Setting the EDGECLAW_API_KEY environment variable before launch will auto-fill it.

4. Verify

node openclaw.mjs agent --local --agent main -m "Hello"

When you see [ClawXrouter] token-saver: S1 redirect → and an agent reply, the deployment is successful.

Dashboard

Panel	URL
ClawXRouter (routing config & stats)	`http://127.0.0.1:18790/plugins/clawxrouter/stats`
ClawXMemory (memory visualization)	`http://127.0.0.1:39394/clawxmemory/`

Having issues? Check the Troubleshooting Guide

🧠 ClawXMemory — Multi-Layered Long-Term Memory System

Developers who have used Claude Code know: what truly makes it indispensable isn't how good any single answer is, but that it remembers you — your coding style, project architecture, last week's discussion, even your preferred naming conventions.

ClawXMemory is the first plugin to bring Claude Code-like memory capabilities to the OpenClaw ecosystem.

Core Memory Capability	Standard OpenClaw	Claude Code	ClawXMemory
Cross-session project knowledge	✗	✓	✓
Persistent user preference	✗	✓	✓
Multi-layered structured memory	✗	✓	✓
Memory integration strategy	Recall	On-demand read	Proactive reasoning
Continuous memory consolidation	✗	Auto-Dream	Auto-consolidation on idle & topic switch

Three-Layer Memory Architecture

The system automatically distills information during conversations, building structured memory layer by layer:

Memory Layer	Type	Description
L2	Project memory / Timeline memory	High-level long-term memory aggregated around specific topics or timelines
L1	Memory fragments	Structured core summaries distilled from concluded topics
L0	Raw conversations	The lowest-level raw message records
Global	User profile	A continuously updated global user preference singleton

When the model needs to recall, it proactively navigates along the "memory tree" through reasoning — first evaluating relevance from high-level memory (project/timeline/profile), drilling down into finer-grained fragments only when needed, and tracing back to specific conversations when necessary. This is closer to how a human expert reasons layer by layer than traditional vector retrieval.

Core Features

Automatic memory construction: No manual maintenance needed — automatically distills, aggregates, and updates during conversation
Model-driven retrieval: Uses reasoning instead of matching, truly understanding vague questions like "How is this project progressing?"
Memory visualization Dashboard: Canvas view and list view, with memory layers and relationships at a glance
Local storage, privacy-safe: SQLite by default, data never leaves the device, supports one-click import/export

For detailed documentation, see ClawXMemory README.

🔌 ClawXRouter — Edge-Cloud Collaborative Routing Plugin

ClawXRouter is EdgeClaw's routing brain — the edge perceives data attributes (sensitivity, complexity) while the cloud handles reasoning and generation. Through its Hook mechanism, it automatically intercepts and routes without any changes to business code, serving as a seamless drop-in replacement for OpenClaw.

Cost-Aware Routing (Token-Saver)

Most requests involve browsing files, reading code, and simple Q&A — using the most expensive model for these tasks is pure waste. Token-Saver uses LLM-as-Judge to classify requests by complexity, automatically routing them to the most economical model:

Complexity	Task Examples	Default Target Model
SIMPLE	Queries, translation, formatting, greetings	`gpt-4o-mini`
MEDIUM	Code generation, single-file editing, email drafting	`gpt-4o`
COMPLEX	System design, multi-file refactoring, cross-doc analysis	`claude-sonnet-4.6`
REASONING	Mathematical proofs, formal logic, experiment design	`o4-mini`

Approach	Pros	Cons
Keyword Rules	Fast	No semantic understanding, high false-positive rate
LLM-as-Judge	Semantic understanding, multilingual	One additional local model call (~1–2s)

The Judge runs on a local small model (MiniCPM-4.1 / Qwen3.5), with prompt hash caching (SHA-256, TTL 5 min) to avoid re-judging identical requests. In typical workflows, 60–80% of requests are forwarded to cheaper models.

Three-Tier Security Collaboration (Privacy Router)

Every message, tool call, and tool result is inspected in real time and automatically classified into three levels:

Level	Meaning	Routing Strategy	Example
S1	Safe	Send directly to cloud model	"Write a poem about spring"
S2	Sensitive	Desensitize then forward to cloud	Addresses, phone numbers, emails
S3	Private	Process locally only	Pay slips, passwords, SSH keys

Dual Detection Engines: Rule detector (keywords + regex, ~0ms) + Local LLM detector (semantic understanding, ~1–2s) — the two can be combined and stacked.

S2 Desensitized Forwarding:

User Message (containing PII) → Local LLM Detection → S2 → Extract PII → Replace with [REDACTED:*]
    → Privacy Proxy → Strip markers → Forward to cloud → Pass through SSE response

S3 Fully Local: Forwarded to the local Guard Agent (Ollama / vLLM); cloud-side history only receives a placeholder.

Dual-Track Memory & Dual-Track Sessions:

~/.edgeclaw/workspace/
├── MEMORY.md           ← What the cloud model sees (auto-desensitized)
├── MEMORY-FULL.md      ← What the local model sees (complete data)
│
agents/{id}/sessions/
├── full/               ← Complete history (including Guard Agent interactions)
└── clean/              ← Clean history (for cloud model consumption)

The cloud model never sees MEMORY-FULL.md or sessions/full/ — the Hook system intercepts at the file access layer.

Composable Router Pipeline

The security router and cost-aware router run in the same pipeline, working together via weights and a two-phase short-circuit strategy:

User Message
    │
    ▼
RouterPipeline.run()
    │
    ├── Phase 1: Fast routers (weight ≥ 50) run in parallel
    │       └── privacy router → three-tier sensitivity detection
    │
    ├── Short-circuit: If Phase 1 detects sensitive data → skip Phase 2
    │
    └── Phase 2: Slow routers (weight < 50) run on demand
            └── token-saver → LLM Judge complexity classification

Security first — the security router runs first with high weight. If sensitive data is found, it short-circuits immediately. Cost-aware routing kicks in only after the security check passes (S1).

13 Hooks Covering the Complete Lifecycle

Hook	Trigger Point	Core Responsibility
`before_model_resolve`	Before model selection	Run pipeline → routing decision
`before_prompt_build`	Before prompt construction	Inject Guard Prompt / S2 markers
`before_tool_call`	Before tool invocation	File access guard + sub-agent guard
`after_tool_call`	After tool invocation	Tool result detection
`tool_result_persist`	Result persistence	Dual-track session write
`before_message_write`	Before message write	S3 → placeholder, S2 → desensitized version
`session_end`	Session ends	Memory synchronization
`message_sending`	Outbound message	Detect and desensitize/cancel
`before_agent_start`	Before sub-agent starts	Task content guard
`message_received`	Message received	Observability logging

For detailed documentation, see ClawXRouter README.

🔧 Custom Configuration

Custom Detection Rules

{
  "privacy": {
    "rules": {
      "keywords": {
        "S2": ["password", "api_key", "token"],
        "S3": ["ssh", "id_rsa", "private_key", ".pem"]
      },
      "patterns": {
        "S2": ["(?:mysql|postgres|mongodb)://[^\\s]+"],
        "S3": ["-----BEGIN (?:RSA |EC )?PRIVATE KEY-----"]
      },
      "tools": {
        "S2": { "tools": ["exec", "shell"], "paths": ["~/secrets"] },
        "S3": { "tools": ["sudo"], "paths": ["~/.ssh", "~/.aws"] }
      }
    }
  }
}

Detector Composition

{
  "privacy": {
    "checkpoints": {
      "onUserMessage": ["ruleDetector", "localModelDetector"],
      "onToolCallProposed": ["ruleDetector"],
      "onToolCallExecuted": ["ruleDetector"]
    }
  }
}

Custom Routers

The ClawXRouter pipeline is fully extensible — implement the GuardClawRouter interface to inject custom routing logic:

const myRouter: GuardClawRouter = {
  id: "content-filter",
  async detect(context, pluginConfig): Promise<RouterDecision> {
    if (context.message && context.message.length > 10000) {
      return {
        level: "S1",
        action: "redirect",
        target: { provider: "anthropic", model: "claude-sonnet-4.6" },
        reason: "Message too long, using larger context model",
      };
    }
    return { level: "S1", action: "passthrough" };
  },
};

{
  "privacy": {
    "routers": {
      "content-filter": {
        "enabled": true,
        "type": "custom",
        "module": "./my-routers/content-filter.js",
        "weight": 40
      }
    },
    "pipeline": {
      "onUserMessage": ["privacy", "token-saver", "content-filter"]
    }
  }
}

Prompt Customization

Edit the Markdown files under extensions/clawxrouter/prompts/ to adjust behavior — no code changes needed:

File	Purpose
`detection-system.md`	S1/S2/S3 classification rules
`guard-agent-system.md`	Guard Agent behavior
`token-saver-judge.md`	Task complexity classification

Provider Preset Quick Switch

Built-in presets allow one-click switching between local model + cloud model combinations:

Preset	Local Model	Cloud Model	Use Case
`vllm-qwen35`	vLLM / Qwen 3.5-35B	Same (fully local)	Full local deployment, maximum privacy
`minimax-cloud`	vLLM / Qwen 3.5-35B	MiniMax M2.5	Local privacy detection + cloud primary model

Custom presets for Ollama, LMStudio, SGLang, and other backends are also supported.

🏗️ Code Structure

EdgeClaw/
├── openclaw.mjs                         # CLI entry point
├── src/config/
│   ├── edgeclaw-defaults.ts             # EdgeClaw default config template (auto-seed)
│   ├── paths.ts                         # State directory / port resolution (18790)
│   └── io.ts                            # Config loading (with auto-seed logic)
├── scripts/
│   ├── deploy-edgeclaw.sh               # One-click deployment script
│   └── lib/optional-bundled-clusters.mjs # Build exclusion list (guardclaw)
│
├── extensions/
│   ├── clawxrouter/                     # [Built-in] ClawXRouter cost-saving router
│   │   ├── index.ts                     # Plugin entry point
│   │   ├── src/
│   │   │   ├── router-pipeline.ts       # Router pipeline (two-phase + weighted merge)
│   │   │   ├── hooks.ts                 # 13 Hooks
│   │   │   ├── privacy-proxy.ts         # HTTP privacy proxy
│   │   │   ├── config-schema.ts         # Default config schema
│   │   │   ├── live-config.ts           # Config hot-reload
│   │   │   ├── stats-dashboard.ts       # Visual Dashboard
│   │   │   └── routers/
│   │   │       ├── privacy.ts           # Privacy router (security)
│   │   │       └── token-saver.ts       # Cost-aware router (cost savings)
│   │   └── prompts/                     # Customizable prompt templates
│   │
│   ├── openbmb-clawxmemory/             # [Built-in] ClawXMemory long-term memory
│   │   ├── src/
│   │   │   ├── index.ts                 # Plugin entry point
│   │   │   ├── core/                    # L0/L1/L2 three-layer memory engine
│   │   │   └── tools.ts                 # memory_overview / memory_list / memory_flush
│   │   └── ui-source/                   # Dashboard frontend
│   │
│   ├── clawxkairos/                     # [Built-in] ClawXKairos self-driven loop
│   │   ├── index.ts                     # Plugin entry point
│   │   └── src/
│   │       ├── tick-scheduler.ts        # Tick scheduling (agent_end → requestHeartbeatNow)
│   │       ├── sleep-tool.ts            # Sleep tool (controlled hibernation)
│   │       ├── background-commands.ts   # Long command auto-backgrounding
│   │       ├── async-subagent.ts        # Async sub-agents
│   │       ├── kairos-prompt.ts         # Autonomous mode system prompt injection
│   │       └── heartbeat-ack-guard.ts   # HEARTBEAT_OK interception → forced Sleep
│   │
│   ├── ClawXSandbox/                    # [Built-in] ClawXSandbox system-level sandbox
│   │   ├── src/
│   │   │   ├── index.ts                # Plugin entry point
│   │   │   ├── bwrap-backend.ts        # bwrap/sandbox-exec sandbox backend
│   │   │   ├── fs-bridge.ts            # File system bridge
│   │   │   └── config.ts              # Sandbox configuration
│   │   └── tests/                      # Unit tests
│   │
# Plugin entry point
│   │   └── src/
│   │       ├── backend.ts              # SSH sandbox backend
│   │       ├── mirror.ts              # Local-remote workspace mirroring
│   │       ├── fs-bridge.ts           # File system bridge
│   │       └── config.ts             # Sandbox configuration
│   │
│   ├── clawxtool/                       # [Built-in] ClawXTool unified tool suite (8-in-1)
│   │   ├── index.ts                     # Unified entry (13 tools + hooks)
│   │   └── src/                         # Tool logic modules
│   │       ├── cron-parser.ts           # Cron expression parsing
│   │       ├── classifier.ts            # Bash command security classification
│   │       ├── secret-patterns.ts       # Secret/key detection patterns
│   │       ├── notebook.ts              # Jupyter notebook read/edit
│   │       ├── worktree.ts              # Git worktree management
│   │       ├── store.ts                 # Task persistence store
│   │       ├── annotate.ts              # Memory age freshness labels
│   │       └── question-tool.ts         # Structured multi-choice questions
│   │
│   ├── clawxskill/                      # [Built-in] ClawXSkill intelligent skill discovery
│   │   ├── index.ts                     # Plugin entry point
│   │   ├── engines/
│   │   │   ├── inverted-index.ts        # BM25 keyword search engine
│   │   │   ├── embedding-search.ts      # Semantic embedding search
│   │   │   └── model-judge.ts           # LLM-based skill relevance judge
│   │   ├── watcher.ts                   # File system skill watcher
│   │   └── skill-backup.ts             # Skill index backup/restore
│   │
│   ├── clawxbuddy/                      # [Built-in] ClawXBuddy virtual pet companion
│   │   └── index.ts                     # Plugin entry point (ASCII sprites, idle animations)
│   │
│   ├── guardclaw/                       # [Optional] Privacy guard (excluded from build by default)
│   │
│   └── clawxgovernor/                   # [Built-in] ClawXGovernor tool governance
│       ├── index.ts                     # Unified entry (3 hook middlewares)
│       ├── src/
│       │   ├── assembler.ts             # Context trimmer (tail-window / compact / reinjection)
│       │   ├── tool-governor.ts         # Tool call interceptor (risk classification / block / loop detection / audit)
│       │   └── session-memory.ts        # Session note appender (delta note / lightweight hint injection)
│       ├── mcp-server/                  # State query interfaces (9 debug tools)
│       └── skills/                      # 4 Agent Skills
│
└── ~/.edgeclaw/                         # Runtime state directory (auto-generated)
    ├── openclaw.json                    # Main config (auto-seeded on first launch)
    ├── clawxrouter.json                 # ClawXRouter config (auto-generated)
    ├── clawxrouter-stats.json           # Token statistics
    ├── clawxmemory/                     # ClawXMemory SQLite data
    ├── clawxgovernor/
    │   ├── context-state.json           # Context engine state
    │   ├── audit.jsonl                  # Tool audit logs
    │   └── notes/                       # Session notes
    └── workspace-main/                  # Agent workspace

🤝 Contributing

Thanks to all contributors for their code submissions and testing. We welcome new members to join us in building the edge-cloud collaborative Agent ecosystem!

Contributing workflow: Fork this repo → Submit Issues → Create Pull Requests (PRs)

⭐ Support Us

If this project is helpful to your research or work, please give us a ⭐!

💬 Contact Us

For technical questions and feature requests, please use GitHub Issues

📖 References

Dependencies

OpenClaw — Base AI assistant framework
MiniCPM — Recommended local detection model
Ollama — Recommended local inference backend

Ecosystem Projects

ClawXRouter — Edge-Cloud collaborative routing plugin (privacy routing + cost-aware routing + Dashboard)
ClawXMemory — Multi-layered memory system for long-term context
ClawXContext — Context engine focused on long-session stability and smoother compaction
ClawXGovernor — Tool governance (context trimming + tool call interception & audit + session notes), EdgeClaw built-in extension
ClawXKairos — Self-driven agent loop (tick scheduling + sleep + background commands + async sub-agents)
ClawXSandbox — Lightweight, zero-dependency isolated execution environment based on system-level sandboxing (bwrap / sandbox-exec)
ClawXTool — Unified 8-in-1 tool suite (cron, bash security, secret scanning, notebooks, git worktrees, tasks, memory age, user questions)
ClawXSkill — Intelligent skill discovery with BM25 keyword search, embedding-based semantic search, and LLM model judge
ClawXBuddy — Virtual pet companion with ASCII sprites, idle animations, and rarity traits

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Secure · Cost-Effective · Efficient

💡 About EdgeClaw

OpenClaw vs Claude Code vs EdgeClaw

✨ Highlights at a Glance

🎬 Demo

📦 Quick Start

1. Build

2. Launch

3. Fill in API Key

4. Verify

Dashboard

🧠 ClawXMemory — Multi-Layered Long-Term Memory System

Three-Layer Memory Architecture

Core Features

🔌 ClawXRouter — Edge-Cloud Collaborative Routing Plugin

Cost-Aware Routing (Token-Saver)

Three-Tier Security Collaboration (Privacy Router)

Composable Router Pipeline

13 Hooks Covering the Complete Lifecycle

🔧 Custom Configuration

Custom Detection Rules

Detector Composition

Custom Routers

Prompt Customization

Provider Preset Quick Switch

🏗️ Code Structure

🤝 Contributing

⭐ Support Us

💬 Contact Us

📖 References

Dependencies

Ecosystem Projects

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Secure · Cost-Effective · Efficient

💡 About EdgeClaw

OpenClaw vs Claude Code vs EdgeClaw

✨ Highlights at a Glance

🎬 Demo

📦 Quick Start

1. Build

2. Launch

3. Fill in API Key

4. Verify

Dashboard

🧠 ClawXMemory — Multi-Layered Long-Term Memory System

Three-Layer Memory Architecture

Core Features

🔌 ClawXRouter — Edge-Cloud Collaborative Routing Plugin

Cost-Aware Routing (Token-Saver)

Three-Tier Security Collaboration (Privacy Router)

Composable Router Pipeline

13 Hooks Covering the Complete Lifecycle

🔧 Custom Configuration

Custom Detection Rules

Detector Composition

Custom Routers

Prompt Customization

Provider Preset Quick Switch

🏗️ Code Structure

🤝 Contributing

⭐ Support Us

💬 Contact Us

📖 References

Dependencies

Ecosystem Projects

License