AutoResearchClaw Architecture Analysis: A Research-Pipeline Operating System Built on a 23-Stage State Machine

Forum topic · ✨步子哥 · 2026-05-27

Summary

This in-depth technical analysis examines the architecture of AutoResearchClaw (ResearchClaw), arguing it is not a simple paper-generation script but a full research-automation operating system. The core is a resumable 23-stage state machine organized into 8 phases (scoping, literature discovery, synthesis, experiment design/execution, analysis, writing, finalization), with gate stages and rollback paths forming feedback loops. The system follows an artifact-first design: stages exchange outputs via file contracts (input files, output files, Definition of Done), enabling checkpoints, heartbeats, resume, HITL review, and dashboard reconstruction. Key subsystems include a unified LLM client factory (OpenAI-compatible, Anthropic, ACP agents), real multi-source literature retrieval (OpenAlex, Semantic Scholar, arXiv) with dedup and caching, 27 configurable domain profiles, multi-backend experiment execution (sandbox, Docker, SSH, Colab, domain-specific external agents), hierarchical agent orchestration (BenchmarkAgent, FigureAgent), a second control plane for human-in-the-loop collaboration, adapter/ports architecture with MCP support, and cross-run learning via Knowledge Base, Memory, Evolution, and MetaClaw. The repository also ships a 55-topic ARC-Bench evaluation suite, a FastAPI server/dashboard, and 85 test files. The analysis concludes the true architectural center is the pipeline's state machine plus stage contracts, with everything else serving as pluggable capabilities.

AutoResearchClaw Architecture Analysis

This post analyzes the architecture of AutoResearchClaw, arguing it is not a single "paper generation script" but a research-pipeline operating system: internally it organizes "topic selection → retrieval → hypothesis → experiments → analysis → writing → review → export" into a resumable, rollback-capable, pluggable 23-stage state machine; externally it exposes a platform drivable by CLI, OpenClaw, ACP agents, web UI, HITL collaboration, external domain agents, and benchmark suites.

Key points

Core thesis: The kernel is a "state machine orchestrator"; most other modules exist to give the state machine capabilities, constraints, memory, collaboration, and output channels.
Repository layering: a composite repo combining a core engine (researchclaw/), docs, an ARC-Bench benchmark (55 topics: ML 25, Physics 10, Quantum 10, Biology 7, Statistics 3), website/frontend assets, and ops scripts.
Main run path: cli.py (a local control plane with init/validate/doctor/run/approve/reject commands) → RCConfig (25+ config sections act as a system-variant assembler) → pipeline/runner.py (checkpoints, heartbeats, resume) → pipeline/executor.py (unified execution protocol) → stage_impls/ (per-stage business logic).

The 23-stage state machine

Defined in pipeline/stages.py: Stage enum, StageStatus, TransitionEvent, explicit advance() logic, gate stages (default 5, 9, 20), gate rollback (5→4, 9→8, 20→16), and research-decision branches (pivot→hypothesis, refine→iterative experiments).
23 stages grouped into 8 phases: Research Scoping, Literature Discovery, Knowledge Synthesis, Experiment Design, Experiment Execution, Analysis & Decision, Paper Writing, Finalization — serving both internal logic and product interaction (CLI status, dashboard, HITL checkpoints).

Artifact-first design

pipeline/contracts.py defines per-stage input_files, output_files, dod (Definition of Done), error_code, and max_retries. Stage outputs are persisted to run_dir/stage-XX/ (goal.md, candidates.jsonl, hypotheses.md, analysis.md, paper_draft.md, quality_report.json, plus checkpoint.json, heartbeat.json, pipeline_summary.json). Artifacts are treated as the only reliable cross-stage interface, enabling recovery, human review, detached interaction, and benchmark judging.

Capability subsystems

LLM abstraction: create_llm_client() unifies OpenAI-compatible, Anthropic, Kimi-Anthropic, and ACP clients; LLMClient keeps a minimal common capability set (fallback model chain, JSON mode, backoff, MetaClaw proxy). ACP extends the system from model caller to agent-orchestration shell.
Prompts: a domain-aware PromptManager with prompt banks (ml, hep_ph, biology_metabolic), YAML overrides, and evolution overlays — prompts as a separate strategy layer.
Literature: real retrieval from OpenAlex, Semantic Scholar, arXiv with multi-source dedup (DOI → arXiv ID → fuzzy title), ranking, caching, and rate-limit tolerance — not model-fabricated references.
Domain routing: 27 YAML domain profiles with experiment paradigms, terminology, baselines/metrics, figure types, prompt hints; detection via forced profile → keywords → LLM classification → generic fallback.
Experiment execution: factory-created backends (sandbox, docker, ssh_remote, colab_drive, collider_agent, biology_agent, stat_agent) plus a code validator and visualization; OpenCode bridge adds complexity-scored routing to a stronger coding agent for hard cases.
Multi-agent: BaseAgent/AgentOrchestrator base classes; BenchmarkAgent (Surveyor→Selector→Acquirer→Validator) and FigureAgent (Decision→Planner→CodeGen→Renderer→Critic→Integrator→image gen) as micro-orchestrators under the macro pipeline.
HITL / Co-Pilot: a second control plane with persistent sessions, per-stage policies, smart pause, claim verification, branching, TUI, and detached attach/approve/reject/guide commands — inserting human judgment only at the highest-value decision points.
Adapters & MCP: hexagonal-style protocols (Cron, Message, Memory, Sessions, WebFetch, Browser) with recording stubs for degraded operation.
Long-term learning: markdown-first Knowledge Base, embedding-based Memory store, JSONL Evolution lessons injected as prompt overlays, and MetaClaw bridging lessons into skills; plus a loadable Skills system.

Quality, delivery, and evaluation

Quality control is multi-layered: preflight/doctor/code validation → stage contracts, gates, HITL, experiment repair → peer review, quality gates, citation verification. Writing/export converts results into drafts, figures, BibTeX, and Overleaf-synced conference output. A FastAPI server and WebSocket dashboard are built from run artifacts, not a separate database; the web frontend is still converging (static site + legacy prototype). External biology/statistics/collider agents are integrated rather than reimplemented, and tests/ contains 85 test files — platform-level regression coverage.

Conclusion

AutoResearchClaw's essential design principles: state machine over prompt chaining; artifact-first over in-memory context; config-driven platformization; hierarchical agent orchestration; HITL as a first-class control plane; real external-world integration; and cross-run learning. Its true architectural center is the relatively plain but critical resumable state-machine skeleton in researchclaw/pipeline/ — without it, the LLM clients, experiment sandboxes, and HITL tooling would have nothing to compose. Costs include a wide repo boundary, a large config surface, and dense cross-subsystem interactions. Recommended reading order: README → cli.py → config.py → pipeline/stages.py → contracts.py → runner.py → executor.py → stage_impls → experiment → domains → hitl → agents → knowledge/memory/evolution → arc_bench.