AutoResearchClaw Architecture Analysis: A 23-Stage State Machine for Research Automation

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

Summary

AutoResearchClaw is analyzed as a research-automation operating system rather than a single paper-generation script. Its core is a 23-stage state machine organized into 8 phases (scoping, literature discovery, synthesis, experiment design and execution, analysis, writing, finalization), orchestrated by a Pipeline Runner and Stage Executor with explicit contracts, checkpointing, heartbeats, and gate-based human approval with rollback paths. The system follows an artifact-first design: all inter-stage state lives on disk, enabling resume, review, detached HITL interaction, and benchmark judging. Capabilities are assembled via configuration (RCConfig), 27 domain profiles, pluggable adapters (ports-and-adapters style), and a skill system. LLM access is unified behind a minimal-protocol client supporting OpenAI-compatible APIs, Anthropic, Kimi, and ACP agents. Literature retrieval uses real sources (OpenAlex, Semantic Scholar, arXiv) with deduplication and caching. Experiment execution supports sandbox, Docker, SSH, Colab, and external domain agents. Subsystems include BenchmarkAgent, FigureAgent, HITL/Co-Pilot control surfaces, knowledge base, memory, evolution lessons, and MetaClaw skills, plus ARC-Bench (55 topics) for evaluation and 85 test files.

AutoResearchClaw Architecture Analysis

Full English translation and structural summary of the original forum analysis. The source argues that AutoResearchClaw is a research workflow operating system, not a single paper-generation script: internally it organizes "topic selection → retrieval → hypothesis → experiment → analysis → writing → review → export" into a resumable, rollback-able, pluggable 23-stage state machine; externally it is a platform drivable by CLI, OpenClaw, ACP Agents, Web UI, HITL collaboration, external domain agents, and benchmark suites.

Key points

Core engine + subsystems + interfaces + assets: the repo is a composite host for a pipeline product (researchclaw/), agent integration docs, HITL/MetaClaw/Memory/Server/Dashboard experiments, ARC-Bench, and website/frontend assets.
Main control path: CLI (researchclaw run, init, validate, doctor, HITL commands) → RCConfig (25+ config sections, profile-driven defaults, config.arc.yaml → config.yaml lookup) → Pipeline Runner → Stage Executor.
State machine first (pipeline/stages.py): 23 stages, 8 phases, explicit transitions, gate stages (5, 9, 20) with rollback (5→4, 9→8, 20→16), and decision-stage feedback loops (pivot → hypotheses, refine → iterative experiments).
Artifact-first design (pipeline/contracts.py): each stage declares input_files, output_files, Definition of Done, error codes, and max retries. Cross-stage state lives in run_dir/stage-XX/ files plus checkpoint.json, heartbeat.json, pipeline_summary.json — enabling recovery, human review, detached interaction, and judge/benchmark reads.
Layered code evolution: stages.py / contracts.py / runner.py / executor.py form a stable kernel; stage business logic lives in stage_impls/ (topic, literature, synthesis, experiment design, code generation, execution, analysis, paper writing, review/publish).
LLM abstraction: create_llm_client() unifies OpenAI-compatible, Anthropic, Kimi, and ACP backends; the client keeps only the minimal capabilities needed (fallback chains, JSON mode, backoff, MetaClaw proxy) — turning the system into an agent orchestration shell rather than a model caller.
Prompt layer: domain-aware PromptManager with per-domain prompt banks (ml, hep_ph, biology_metabolic), YAML overrides, per-stage extra prompts, and evolution overlay injection.
Real literature retrieval: OpenAlex, Semantic Scholar, arXiv, scholarly crawling and PDF extraction, with DOI/arXiv-ID/fuzzy-title dedup, ranking, caching, and rate-limit tolerance — not model-hallucinated references.
Domain routing: 27 YAML DomainProfile files (experimental paradigms, terminology, entry points, baselines/metrics, figure types, prompt hints, deployment defaults); detection cascades forced profile → keywords → LLM classification → generic fallback.
Experiment execution backends (factory pattern): sandbox, docker (GPU passthrough, network policy), SSH remote, Colab via Drive polling, plus agentic and domain-specific agent sandboxes; separate validator.py (syntax/safety/import checks) and visualize.py.
Code-agent bypass: opencode_bridge.py performs complexity scoring (component complexity, multi-file signals, ablations, failure history, dependency depth) to route hard code generation to the OpenCode CLI — cost/reliability-aware strategy routing.
Layered agent orchestration: the main pipeline is a macro orchestrator; BenchmarkAgent (Surveyor/Selector/Acquirer/Validator) and FigureAgent (Decision/Planner/CodeGen/Renderer/Critic/Integrator/image-gen) are micro orchestrators built on BaseAgent/AgentOrchestrator.
HITL / Co-Pilot as a second control plane: persistent HITL sessions, intervention modes, per-stage policies, detached attach/approve/reject/guide, smart pause, claim verification, branching, TUI and workshops — treating humans as a scarce, high-value compute resource inserted only at decision-critical gates.
Adapters (hexagonal architecture): CronAdapter, MessageAdapter, MemoryAdapter, SessionsAdapter, WebFetchAdapter, BrowserAdapter, aggregated in an AdapterBundle, with recording stubs when platforms are absent; dedicated MCP client/server/tools/transport.
Long-term memory stack: Knowledge Base (readable markdown/Obsidian logs of questions, literature, experiments, findings, decisions, reviews), Memory store (embedding-backed short/mid-term retrieval), Evolution (JSONL lessons that become prompt overlays for future runs), MetaClaw (lesson-to-skill, skill effectiveness tracking, PRM gate).
Skills system: SKILL.md plus YAML/JSON legacy formats with registry/matcher/loader — a third extension axis beyond code changes and config/profile changes.
Multi-layered quality control: preflight/doctor/validator upfront; stage contracts, gate approvals, HITL pauses, experiment diagnosis/repair in-process; peer review, quality gates, citation verification, and verified registries downstream — stacked weak guarantees rather than trusting any single stage.
Writing/export as a compilation chain: outline/draft/review/revision generation, figures, tables, BibTeX, conference-specific output, Overleaf sync, and quality scoring.
Server/Dashboard: FastAPI app with /api/health, /api/config, pipeline/projects/chat/voice routes and /ws/events WebSocket; the dashboard reconstructs views from run artifacts rather than a separate database. The web surface (static website/, frontend-legacy/, expected frontend/ mount) is still converging.
External agents: Biology-Agent, stat_research_agent, ColliderAgent handle domain scientific computing; AutoResearchClaw orchestrates — detect domain, pick experiment mode, prepare workspace/prompts/skills, invoke, collect results.
ARC-Bench: 55 topics (ML 25, Physics 10, Quantum 10, Biology 7, Statistics 3) serving as external comparison baseline (vs AIDE, AgentLaboratory, AI Scientist v2), internal regression field, and method-paper asset.
Testing: 85 test files covering CLI, config, pipeline internals, literature, LLM, HITL end-to-end, agents, MCP, MetaClaw, Overleaf, memory, dashboard, and server — platform-scale regression coverage.

Design philosophy

1. State machine over prompt chaining 2. Artifact-first over in-memory context 3. Configuration-driven platformization (config / profile / adapter / skill) 4. Layered macro/micro agent orchestration 5. Human-in-the-loop as a primary path, not a patch 6. Real external-world contact (literature APIs, experiment backends, ACP/MCP/OpenClaw) 7. Cross-run learning (Knowledge, Memory, Evolution, MetaClaw)

Strengths and costs

Strengths: strong resumability (checkpoint + artifact + heartbeat + sentinel), easy auditability, clear extension points, coexisting run modes (full-auto, gate-only, co-pilot, ACP/OpenClaw, web server) on one kernel, and research realism (real literature, real experiments, quality gates, citation checks).

Costs: wide repo boundaries raise comprehension cost; the large RCConfig surface adds cognitive load; stages intersect many subsystems (prompt, LLM, profile, HITL, adapters, KB, quality, backend), requiring systemic debugging; the web frontend is still evolving.

Conclusion

AutoResearchClaw is best understood as a research automation platform whose true center is the recoverable state-machine skeleton in researchclaw/pipeline/ (stages + contracts + execution protocol), with LLM clients, experiment backends, HITL, and memory systems all existing to feed, constrain, remember, collaborate with, and export from that core.