openclaw-finance

Multi-agent financial research system built on OpenClaw

OpenClaw · Architecture · Communication · Quick Start

This framework has been used in a 7-agent Telegram workflow for US and A-share financial research. Verify the current runtime status before relying on it operationally.

Clone. Configure API keys. Run. 4 specialized agents collaborate on financial research with built-in quality control — no single agent can match what a team delivers.

Why Multi-Agent?

Traditional financial research is linear. Information decays at each handoff:

PM → Analyst → Programmer → Output
     ↑ Information decay at each step

openclaw-finance replaces this with parallel, self-validating agents:

Parallel processing — Multiple specialists work simultaneously
Built-in quality control — A dedicated skeptic challenges every assumption
Shared context — All agents access the same knowledge base in real-time
Traceable decisions — Every step is logged and auditable
Self-healing — Heartbeat monitoring auto-recovers failed agents

Architecture

┌─────────────────────────────────────────────┐
│                  User Request               │
└──────────────────┬──────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│           Coordinator (Chat Agent)           │
│  • Task decomposition & dispatch             │
│  • Result integration                        │
│  • Health monitoring via heartbeat           │
└──┬──────────┬──────────┬──────────┬─────────┘
   ▼          ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐
│Engineer│ │Engineer│ │Skeptic │ │Visualizer│
│ (Code) │ │(Linus) │ │  (FP)  │ │ (Vision) │
│        │ │        │ │        │ │          │
│ Data & │ │Parallel│ │Challenge│ │ Charts & │
│Backtest│ │  Load  │ │Validate│ │ Reports  │
│        │ │Balance │ │        │ │          │
└────────┘ └────────┘ └────────┘ └──────────┘
        ▲          ▲          ▲          ▲
        └──────────┴──────────┴──────────┘
                       │
              ┌────────┴────────┐
              │  Knowledge Hub  │
              │ (Shared State)  │
              └─────────────────┘

Key Design Decisions

Decision	Why
Shared workspace	Zero-latency knowledge sharing, no sync overhead
Per-agent identity	Auth isolation + role clarity without file duplication
Bootstrap hooks	Dynamic identity injection at startup
3-layer memory	Auto-recall (LanceDB) + manual index (MEMORY.md) + daily logs
Staggered heartbeats	Avoid thundering herd, 79-120min intervals

Agent Roles

Agent	Role	What It Does
Coordinator	Orchestrator	Decomposes requests, dispatches tasks, integrates results
Engineer (x2)	Data & Backtest	Python/pandas pipelines, ETL, backtesting, load-balanced pair
Skeptic	Quality Control	Bias detection, assumption challenging, statistical validation
Visualizer	Reports & Charts	Matplotlib/Plotly charts, PDF/HTML reports, dashboards

Quick Start

Prerequisites

OpenClaw installed (npm i -g openclaw)
At least one LLM API key (OpenAI, Qwen, GLM, Ollama, etc.)

1. Clone & Configure

git clone https://github.com/zhangsensen/openclaw-finance.git
cd openclaw-finance

# Copy example config and add your API keys
cp examples/openclaw-config-example.json ~/.openclaw/openclaw.json
vim ~/.openclaw/openclaw.json

2. Set Up Workspace

bash scripts/setup.sh /path/to/your/workspace

This creates the full workspace structure with agent identities, shared rules, and knowledge hub.

3. Start

openclaw gateway restart

Open Telegram, message your coordinator bot:

"Analyze AAPL with quality checks"

The system automatically:

Engineer loads price data
Skeptic prepares validation checklist
Engineer calculates metrics
Skeptic validates results (survivorship bias, look-ahead bias, etc.)
Visualizer generates report
Coordinator delivers integrated output

Try the Demo Locally

cd examples/stock-analysis
pip install pandas numpy
python run_analysis.py --stock AAPL

Communication Patterns

Spawn — Task Delegation

sessions_spawn({
  agentId: "engineer",
  task: "Load and validate AAPL price data from 2023-01-01 to 2025-12-31"
})

A2A — Point-to-Point Dialogue

sessions_send({
  sessionKey: "agent:engineer:main",
  message: "Did you exclude stocks with insufficient trading days?",
  timeoutSeconds: 60
})

Safety Rules

Never call sessions_send inside an A2A conversation (causes deadlock)
Max 5 ping-pong rounds per dialogue
Respond with text, never with another sessions_send

See docs/communication.md for complete patterns.

Memory System

Layer	Mechanism	Effort
Auto-Recall	LanceDB vector + BM25 hybrid	Zero (automatic)
MEMORY.md	Project index + hard rules	Low (manual, <5000 chars)
Daily Notes	`memory/YYYY-MM-DD.md`	Medium (raw logs, auto-extracted)

Project Structure

openclaw-finance/
├── agents/
│   ├── coordinator/     # Orchestrator identity & rules
│   ├── engineer/        # Data engineer identity & rules
│   ├── skeptic/         # Quality controller identity & rules
│   └── visualizer/      # Chart/report generator identity & rules
├── knowledge_hub/
│   ├── agent_coordination/   # Output specs + project state
│   └── example_project/      # Template with MARKET_CONTEXT.md
├── scripts/
│   ├── setup.sh              # One-command workspace setup
│   └── sync-bootstrap.sh     # Sync rules across agents
├── examples/
│   ├── openclaw-config-example.json
│   └── stock-analysis/       # Runnable demo
├── docs/
│   ├── architecture.md       # Deep dive (EN + CN)
│   └── communication.md      # A2A patterns & safety
├── AGENTS.md                 # Shared behavioral rules
├── TOOLS.md                  # Shared tool catalog
└── LICENSE                   # MIT

Open Source Boundary

Open Source (This Repo)	Keep Private (Your Work)
Agent collaboration patterns	Factor formulas
Communication protocols	Strategy parameters
Memory system design	Proprietary data sources
Heartbeat monitoring	Alpha generation logic
Bootstrap templates	Trading signals

中文说明