Architecture

apps/
  server/     HTTP gateway (127.0.0.1:18790, localhost-only)
  cli/        CLI commands (onboard, agent, gateway, doctor, security)
  web/        Vite + React portal UI (dashboard, chat, plugins, settings)

packages/
  core/       Agent loop, tools, plugins, memory, control plane, policy
  storage/    Local JSON file stores (state/*.json, ~/.clawmagic/)
  connectors/
    ai/       Multi-provider LLM routing (OpenAI, Anthropic, Google, etc.)
    local/    Safe command runner + file adapters
    github/   PR creation, repo operations
    marketplace/  ClawMagic Marketplace API client

plugins/      Plugin ecosystem (installed, disabled, examples, bundled)
skills/       Repo-level skill manifests and documentation
tools/        Build/validation scripts (boundary checks, safety invariants)
state/        Local-first persistent stores (queue, memory, approvals, routing)
templates/    Workspace templates
scripts/      Installation, upgrade, setup scripts

User message (Portal UI or CLI)
  │
  ▼
POST /api/chat/send  or  POST /api/run
  │
  ▼
Control-plane queue (state/queue.json)
  │
  ▼
LocalControlPlaneQueueRunner (polls, leases job)
  │
  ▼
runAgentLoop()  [packages/core/src/agent/loop.ts]
  ├── buildAgentContext()     — config, memory, contract, routing
  ├── buildCoreSystemPrompt() — system prompt, token budget
  ├── Tool loop:
  │   ├── LLM call via ToolLoopProvider (AI provider)
  │   ├── evaluateToolCall() — policy gating (ALLOW/DENY/REQUIRE_APPROVAL)
  │   ├── Execute tool (builtin, plugin, or connector)
  │   └── Append to message history
  └── Return final reply
  │
  ▼
Store result → Update session

The core package exports 100+ symbols across these subsystems:

• Agent loop: main execution loop with tool invocation, context building, system prompt generation, reasoning support, sub-agent delegation, and context compaction.
• Tools (16+ builtin): file read/write, git operations, browser automation, web fetch/search, session management, cron scheduling, messaging, marketplace operations, memory append/query, and ActionSpec lookup.
• Plugin system (50+ modules): discovery, validation, installation, activation, execution, rollback, security review, quarantine, signature verification, SBOM generation, and OpenClaw compatibility.
• Memory: long-term memory with BM25 + vector search, temporal decay, promotion lifecycle, chunking, and distillation.
• Control plane: local file store with queue runner, lease-based job ownership, and status tracking.
• Policy: tool execution gating, approval management, prompt injection detection, command obfuscation detection, sandbox profiles, and safe regex.
• ActionSpec: optional spec-packeting subsystem for deterministic tool selection with risk-tiered confirmation.

All execution state lives locally. No external database is required for the core agent runtime.

state/
  queue.json              # Job queue (status, message, lease)
  approvals.json          # Pending tool approvals
  tasks.json              # Tickets (Backlog/Ready/Doing/Done)
  memory.json             # Long-term agent memory
  contracts.json          # User/agent contracts
  routing.json            # Agent routing rules
  providers.json          # LLM provider/model config
  chat_sessions.json      # Chat history
  person_details.json     # Human/agent persona

~/.clawmagic/
  config.json             # Runtime config
  secrets.json            # Encrypted secrets (chmod 600, AES-256-GCM)
  logs/YYYY-MM-DD.jsonl   # Daily work log

1. Discovery: loader scans plugins/ directories for plugin.json manifests.
2. Validation: AJV-based config schema validation, security scanning, and malicious pattern detection.
3. Installation: ZIP extraction to plugins/installed/<id>/ with zip-slip protection and checksum verification.
4. Activation: hooks registered, tools added to registry, plugin memory initialized.
5. Execution: tools invoked via agent loop, hooks triggered on events, policy gates applied.
6. Rollback: versioned backups stored in plugins/backups/<id>/<version>/ for safe rollback.

Plugins can be sourced from the ClawMagic Marketplace (via API), installed manually from ZIP files, or bundled with the repo (discord, slack, telegram, whatsapp, email connectors).

The ClawMagic Marketplace is the Agent-First economy where users and agents buy, sell, and promote tools to earn money. With 100+ plugins available, the marketplace connects to ClawMagic core via a typed API client.

• Browse and install: the agent or user discovers plugins via GET /v1/plugins, purchases via Stripe, and downloads signed ZIP packages.
• Sell: plugin developers submit packages through the marketplace API. After review, plugins are listed and earn revenue on every sale.
• Wallet: the wallet bridges both systems. Sellers earn commissions, affiliates earn referral income, and buyers earn first-purchase bonuses. Payouts are processed outside the system for security and tax compliance.
• Promote: referral codes and affiliate links let anyone earn commission by promoting plugins and driving sales.
• Marketplace connector: packages/connectors/marketplace/ provides the typed API client. Builtin marketplace_tools.ts exposes marketplace operations as agent tools.

The server exposes internal APIs for the portal UI and CLI. Key route groups:

Idempotency keys are required on POST /api/run, POST /api/chat/send, and POST /api/messaging/send.

• Local-first, database optional: all state lives in JSON files. No Postgres/Redis required for the core agent runtime.
• Single-threaded agent loop: agent lock prevents concurrent runs. Queue runner processes one job at a time via lease ownership.
• Localhost-only by default: server binds to 127.0.0.1:18790. No remote exposure without explicit config change.
• Approval-gated execution: tool policy evaluates every tool call. High-risk operations (write, git push, core changes) require approval.
• Memory as core feature: long-term memory with BM25 + vector search, temporal decay, promotion lifecycle, and distillation built into the agent loop.
• Agent-First economy: the Marketplace is the economy layer where agents and users buy, sell, and promote plugins to earn money. Wallet bridges both systems. Payouts handled externally for security and tax compliance.
• BYOK (Bring Your Own Key): users provide their own LLM API keys. No built-in key sharing or proxy.