Tools
Claw Swarm 8x
By Bio-inspired swarm intelligence plugin for OpenClaw — pheromone coordination, 3-tier memory, DAG orchestration, contract-net auction, 6-view monitoring console
Install
npm install -gREADME
<p align="center">
<img src="docs/assets/console-demo.gif" alt="Claw-Swarm Console" width="90%">
</p>
<h1 align="center">Claw-Swarm</h1>
<p align="center">
Field-Mediated Swarm Intelligence for Multi-Agent LLM Coordination<br/>
面向多代理 LLM 协作的场中介蜂群智能系统
</p>
<p align="center">
<img src="https://img.shields.io/badge/version-9.0.0-blue" alt="Version">
<img src="https://img.shields.io/badge/tests-1365_passing-green" alt="Tests">
<img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License">
<img src="https://img.shields.io/badge/Node.js-≥22-green" alt="Node">
<img src="https://img.shields.io/badge/domains-7-orange" alt="Domains">
<img src="https://img.shields.io/badge/models-35+-purple" alt="Models">
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> ·
<a href="#documentation">Docs</a> ·
<a href="#llm-docs">LLM Docs</a> ·
<a href="CHANGELOG.md">Changelog</a>
</p>
---
## Origin Story · 起源故事
The existing multi-agent frameworks share a fatal assumption: **coordination is a messaging problem**. Build a message bus, add some routing, and agents will collaborate. They don't. In production, they collide, forget, cascade-fail, and degrade into expensive echo chambers.
现有多代理框架共享一个致命假设：**协调是一个消息传递问题**。搭建消息总线、加上路由，代理就会协作。事实是：它们不会。在生产环境中，它们碰撞、遗忘、级联失败，最终退化为昂贵的回音室。
Claw-Swarm was born from a different observation: **nature solved coordination billions of years ago**. Ant colonies with 250-neuron brains outperform human logistics. Immune systems classify threats without central command. Neural circuits self-organize through reaction-diffusion dynamics.
Claw-Swarm 诞生于一个不同的观察：**大自然在数十亿年前就解决了协调问题**。拥有 250 个神经元的蚂蚁群落在物流效率上超越人类。免疫系统无需中央指挥就能分类威胁。神经回路通过反应-扩散动力学自组织。
This led to a 14-discipline cross-research program spanning entomology, immunology, cognitive science, graph theory, evolutionary biology, network sociology, information theory, control theory, game theory, morphogenesis, organizational psychology, cultural anthropology, affective computing, and computational ecology — each discipline contributing a concrete algorithm, not metaphors, to the codebase.
这催生了一个横跨 14 个学科的交叉研究计划——昆虫学、免疫学、认知科学、图论、进化生物学、网络社会学、信息论、控制论、博弈论、形态发生学、组织心理学、文化人类学、情感计算和计算生态学——每个学科贡献了一个具体的算法，而非隐喻。
The result: **V9.0 introduces a Field-Mediated Coupling Architecture** — seven autonomous domains connected not by point-to-point wiring, but by a shared 12-dimensional signal field. Agents leave traces in this field like ants depositing pheromones; decisions emerge from the superposition of all signals, not from any central controller. No idle modules. No feature flags. Every line of code runs in production.
成果：**V9.0 引入了场中介耦合架构**——七个自治域并非通过点对点连线相连，而是通过共享的 12 维信号场沟通。代理在场中留下痕迹，如同蚂蚁沉积信息素；决策从所有信号的叠加中涌现，而非来自某个中心控制器。没有空转模块。没有功能开关。每一行代码都在生产环境运行。
---
## The Problem · 真实痛点
Coordinating multiple LLM agents in production hits **six walls**:
在生产环境中协调多个 LLM 代理会撞上**六面墙**：
| Wall · 痛点 | What breaks · 崩溃现象 | How Claw-Swarm fixes it · 解法 |
|---|---|---|
| **Blind collaboration** · 协作盲区 | Agents duplicate work, no shared awareness · 代理重复劳动，彼此毫无感知 | 12-dim signal field + pheromone trails · 12 维信号场 + 信息素踪迹 |
| **Memory loss** · 记忆断裂 | Context resets erase all knowledge · 上下文重置后知识全部丢失 | 3-tier hybrid memory with Ebbinghaus decay · 三层混合记忆 + 遗忘曲线 |
| **Cascading failures** · 级联故障 | One tool timeout kills the pipeline · 单个工具超时拖垮整条流水线 | 6-layer resilience: retry → breaker → vaccine → model fallback → replan → pipeline break · 六层容错 |
| **Manual routing** · 手动路由 | Every task must be hand-assigned · 每项任务都要人工分配 | DAG decomposition + field-aware spawn advisor · DAG 分解 + 场感知孵化建议 |
| **Zero observability** · 零可观测性 | No runtime insight into agent behavior · 运行时完全看不到代理行为 | Dashboard (57+ REST) + SSE streaming + health checks · 仪表盘 + SSE 实时流 + 健康检查 |
| **Idle code** · 空转代码 | Feature-flagged modules never activate · 功能开关后的模块从不激活 | Zero flags: all modules unconditionally active, field-mediated coupling verification · 零开关：所有模块无条件激活，场耦合验证 |
---
## Architecture Overview · 架构一览
V9.0 replaces the 7-layer linear hierarchy (L0–L6) with **7 autonomous domains** connected through a **dual foundation** (SignalField + DomainStore + EventBus). Modules interact through the signal field, not through direct imports.
V9.0 将 7 层线性层级（L0–L6）替换为**7 个自治域**，通过**双基座**（信号场 + 域存储 + 事件总线）连接。模块通过信号场交互，而非直接导入。
```
Domain · 域 Files · 文件 Lines · 行数 Responsibility · 职责
───────────────── ──────────── ────────── ────────────────────────────
core 12 1,953 SignalField, DomainStore, EventBus, ModuleBase
核心 信号场、域存储、事件总线、模块基类
communication 8 1,281 Pheromones (MMAS), task channels, stigmergic board
通信 信息素引擎、任务通道、痕迹协作板
intelligence 34 5,606 Memory, identity, social, artifacts, understanding
智能 记忆、身份、社交、产物、理解
orchestration 24 6,889 DAG planner, spawn advisor, adaptation, scheduling
编排 DAG 规划、孵化建议、自适应、调度
quality 10 2,738 Evidence gate, circuit breaker, failure vaccination
质量 证据门控、熔断器、失败疫苗
observe 13 1,651 Dashboard (57+ REST), metrics, health, SSE broadcast
观测 仪表盘、指标、健康检查、SSE 广播
bridge 24 4,526 10 tools, 16 hooks, session, model fallback
桥接 10 工具、16 钩子、会话、模型降级
───────────────── ──────────── ──────────
Total · 合计 121 25,447
```
**Process Model · 进程模型:**
```
OpenClaw Gateway (Node.js)
┌────────────────────────────────────────────────────────────────────┐
│ index.js (plugin adapter) │
│ ├── gateway_start hook → activateV9(app) │
│ │ └── SwarmCoreV9.start() │
│ │ ├── SignalField (12-dim, forward-decay, GC scheduler) │
│ │ ├── DomainStore (in-memory + JSON snapshots) │
│ │ ├── EventBus (pub/sub, 27+ event topics) │
│ │ └── 5 domain factories (comm/intel/orch/qual/observe) │
│ ├── HookAdapter: 16 hooks registered on app │
│ └── ToolRegistry: 10 tools registered on app │
│ │
│ DashboardService :19100 (in-process HTTP server) │
└────────────────────────────────────────────────────────────────────┘
```
V9 runs entirely in-process within the OpenClaw Gateway. No `child_process.fork()`. No IPC timeout. The `SwarmCoreV9` constructor assembles all domains through dynamic imports with graceful fallback.
V9 完全在 OpenClaw Gateway 进程内运行。不再有 `child_process.fork()`。没有 IPC 超时。`SwarmCoreV9` 构造器通过动态导入组装所有域，支持优雅降级。
**Source · 源码:** [`src/swarm-core-v9.js`](src/swarm-core-v9.js) (475 lines), [`src/index.js`](src/index.js) (205 lines)
> [Architecture (EN)](docs/en/architecture.md) · [架构设计 (中文)](docs/zh-CN/architecture.md)
---
## 12-Dimensional Signal Field · 12 维信号场
The signal field is the **shared medium** through which all domains communicate. Every coordination event is a signal carrying a scope, a dimension, and an intensity that decays over time via forward-decay encoding.
信号场是所有域通信的**共享介质**。每个协调事件都是一个信号，携带作用域、维度和强度，并通过前向衰减编码随时间衰减。
| # | Dimension · 维度 | Biological Analog · 生物学类比 | Decay Rate λ | Meaning · 含义 |
|---|---|---|---|---|
| 1 | `task_load` | Worker ant trail density · 工蚁踪迹密度 | 0.02 | Task queue pressure across the swarm · 蜂群任务队列压力 |
| 2 | `error_rate` | Alarm pheromone · 警报信息素 | 0.10 | Rolling error frequency · 滚动错误频率 |
| 3 | `latency` | Neural conduction delay · 神经传导延迟 | 0.05 | Response time distribution · 响应时间分布 |
| 4 | `throughput` | Colony metabolic rate · 群落代谢率 | 0.03 | Messages processed per unit time · 单位时间处理消息数 |
| 5 | `cost` | Foraging energy cost · 觅食能量成本 | 0.02 | Token and API cost accumulation · Token 与 API 成本累积 |
| 6 | `quality` | Nectar quality gradient · 花蜜质量梯度 | 0.03 | Output quality scores · 输出质量评分 |
| 7 | `coherence` | Queen pheromone · 蜂后信息素 | 0.04 | Inter-agent goal alignment · 代理间目标对齐度 |
| 8 | `trust` | Mutualistic grooming · 互惠梳理 | 0.01 | Peer trust and reputation · 同伴信任与声誉 |
| 9 | `novelty` | Waggle dance intensity · 摇摆舞强度 | 0.06 | Divergence from known patterns · 偏离已知模式程度 |
| 10 | `urgency` | Alarm response cascade · 警报响应级联 | 0.08 | Time-sensitivity pressure · 时间敏感压力 |
| 11 | `complexity` | Cognitive load indicator · 认知负载指示 | 0.04 | Estimated task difficulty · 估算任务难度 |
| 12 | `resource_pressure` | Nest capacity signal · 巢穴容量信号 | 0.03 | Memory, context, budget saturation · 内存、上下文、预算饱和度 |
All signals decay via **forward-decay encoding**: `score = base × e^(λ × emitTime)`. Query-time evaluation ensures O(1) emission and O(n) query. Emergency GC triggers when signal count exceeds 100,000.
所有信号通过**前向衰减编码**衰减：`score = base × e^(λ × emitTime)`。查询时求值确保 O(1) 发射和 O(n) 查询。信号数超过 100,000 时触发紧急 GC。
**Source · 源码:** [`src/core/field/signal-store.js`](src/core/field/signal-store.js) (382 lines), [`src/core/field/forward-decay.js`](src/core/field/forward-decay.js) (108 lines)
> [Signal Field Deep Dive (EN)](docs/en/signal-mesh.md) · [信号场详解 (中文)](docs/zh-CN/signal-mesh.md)
---
## How It Works · 系统如何运作
A task flows through six emergent phases — not a hardcoded pipeline, but stages that **naturally arise from signal-field dynamics**.
一个任务流经六个涌现阶段——不是硬编码的流水线，而是从**信号场动力学中自然涌现**的阶段。
### Phase 1: Intent Recognition · 意图识别
The system classifies incoming messages into **fast-think (System 1)** or **slow-think (System 2)** pat
... (truncated)
tools
Comments
Sign in to leave a comment