Architecture

Design Principle: AcaClaw is a distribution, not a fork. Every customization lives in OpenClaw’s extension points — skills, plugins, configuration, and environment. Zero source code modifications.

Design Philosophy

Target Users

AcaClaw is designed for scientists who are not software engineers: chemists, physicists, biologists, medical researchers, and students. Every design decision must pass this test: “Would a biology grad student who has never opened a terminal be able to use this?”

The Ubuntu Analogy

Core Principles

1. Non-invasive — Never modify OpenClaw source code. Work through skills, plugins, config, and environments.
2. One best — For each capability, ship exactly one tool — the best one. Pre-configured. Works out of the box.
3. Data is sacred — Every file modification is preceded by automatic backup. No exceptions.
4. Zero-knowledge UX — Users should never encounter “install X dependency” or “run this command”.
5. Layered independence — AcaClaw sits ON TOP of OpenClaw, never below. OpenClaw can be upgraded independently.
6. Security-first — Stricter defaults than upstream. Workspace-restricted by default.
7. Contribute, don’t diverge — Every skill is published to ClawHub. We never maintain a parallel ecosystem.
8. Environment compatibility — Every pre-shipped skill is tested together in a single curated environment.
9. Don’t re-implement — Never re-implement what OpenClaw already provides. Use it, display it, configure it through OpenClaw’s APIs.

Responsibility Boundary

AcaClaw is a distribution layer — it builds on top of OpenClaw, not alongside it. The following table defines what each layer owns:

See Providers & Models for the full provider architecture, model mapping, API reference, and AcaClaw GUI integration method.

The Golden Rule

If OpenClaw already does it, don’t re-implement it. AcaClaw’s UI and OpenClaw’s UI are both frontends to the same OpenClaw backend. The functionality is implemented once — in OpenClaw. Both UIs just use and display it.

Configuration

AcaClaw writes to OpenClaw’s config using config.get + config.set (WebSocket RPC read-modify-write). The correct way to set a provider API key:

# Via environment variable (recommended for AcaClaw UI)
# AcaClaw writes to config.env so OpenClaw's plugin catalog discovers the key
openclaw config set env.MOONSHOT_API_KEY "sk-..."

# Via CLI (equivalent)
openclaw config set models.providers.openrouter.apiKey "sk-or-..."

# Via shell environment variable
export OPENROUTER_API_KEY="sk-or-..."

AcaClaw’s UI saves API keys to config.env.<ENV_VAR> (not models.providers). OpenClaw’s applyConfigEnvVars copies these into process.env at gateway startup, so the plugin catalog discovers the key and creates the implicit provider config (including base URLs, API type, and model list). This delegates all provider complexity to OpenClaw extensions.

Layer Model

┌─────────────────────────────────────────────────────────────┐
│  Layer 6: AcaClaw Web GUI (design: /en/desktop-gui/)          │
│  Research-focused interface — no terminal needed             │
├─────────────────────────────────────────────────────────────┤
│  Layer 5: User Workspace                                     │
│  User-installed ClawHub skills, personal data, projects      │
├─────────────────────────────────────────────────────────────┤
│  Layer 4: Curated Academic Skills (from ClawHub + bundled)    │
│  Installed via clawhub CLI, organized in acaclaw-skills repo │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: AcaClaw Plugins                                    │
│  @acaclaw/workspace, @acaclaw/security, @acaclaw/backup,    │
│  @acaclaw/academic-env, @acaclaw/compat-checker              │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: AcaClaw Environment                                │
│  Miniforge + Python + R (opt-in) + Conda envs on demand      │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: OpenClaw (Upstream, Unmodified)                     │
│  Gateway · Agent · Plugin SDK · Skill System · CLI           │
├─────────────────────────────────────────────────────────────┤
│  Layer 0: Operating System / Container Runtime               │
│  Windows · macOS · Linux                                     │
└─────────────────────────────────────────────────────────────┘

Layer Interaction Rules

Directory Layout

AcaClaw uses two directories at runtime. Each has a clear purpose:

~/.openclaw/                      ← OpenClaw directory (config + managed state)
├── openclaw.json                 ← Single source of truth for ALL config
│   ├── models.providers.*        ← API keys, provider auth (OpenClaw handles)
│   ├── agents.*                  ← Agent definitions, default model (OpenClaw)
│   └── (future) acaclaw.*       ← AcaClaw plugin config (via config.set)
├── extensions/                   ← Installed OpenClaw extensions
├── skills/                       ← Installed skills
├── agents/                       ← Agent session data
├── ui/                           ← AcaClaw web UI (served by gateway)
├── memory/, logs/, completions/  ← OpenClaw runtime data
└── identity/                     ← Gateway identity

~/.acaclaw/                       ← AcaClaw runtime DATA only (not config)
├── backups/                      ← Versioned file backups (large data)
├── audit/                        ← Security audit logs (append-only)
├── config/                       ← [MIGRATION PENDING] → openclaw.json
│   ├── plugins.json              ← → acaclaw.* in openclaw.json
│   ├── security-mode.txt         ← → agents.defaults.sandbox.mode
│   └── setup-pending.json        ← → acaclaw.setup.* in openclaw.json
├── gateway.log                   ← Gateway runtime log
├── start.sh, stop.sh             ← Runtime scripts
└── browser-app/                  ← Electron/browser app data

Design Principles

Migration Plan

~/.acaclaw/config/ currently holds AcaClaw plugin settings that should migrate into openclaw.json. Until migration is complete:

• plugins.json settings will move to acaclaw.* namespace in openclaw.json
• security-mode.txt will use agents.defaults.sandbox.mode
• setup-pending.json will use acaclaw.setup.* namespace
• After migration, ~/.acaclaw/config/ will be removed
• ~/.acaclaw/ will contain only runtime data: backups, audit logs, gateway log, scripts

The “One Best” Principle

AcaClaw ships one best tool per job, pre-configured and tested together.

Selection Criteria

What We Deliberately Exclude

Component Architecture

acaclaw/
├── plugins/                          # OpenClaw plugins (npm packages)
│   ├── workspace/                    # @acaclaw/workspace
│   ├── backup/                       # @acaclaw/backup
│   ├── security/                     # @acaclaw/security
│   ├── academic-env/                 # @acaclaw/academic-env
│   └── compat-checker/               # @acaclaw/compat-checker
│
├── skills.json                       # Curated skill manifest
├── env/conda/                        # Environment definitions
│   ├── environment-base.yml          # General academic (acaclaw)
│   ├── environment-bio.yml           # Biology (acaclaw-bio)
│   ├── environment-chem.yml          # Chemistry (acaclaw-chem)
│   ├── environment-med.yml           # Medicine (acaclaw-med)
│   └── environment-phys.yml          # Physics (acaclaw-phys)
│
├── config/                           # Configuration overlays
│   ├── openclaw-defaults.json        # AcaClaw defaults
│   └── openclaw-maximum.json         # Maximum security policy
│
├── scripts/
│   ├── install.sh                    # One-line installer
│   └── uninstall.sh                  # Uninstaller
│
└── docs/                             # Documentation (this site)

Skill Architecture

AcaClaw curates, creates, tests, and publishes high-quality academic skills to ClawHub so the entire OpenClaw community benefits.

Contribute, Don’t Diverge

Contributor Attribution Model

Every AcaClaw skill includes a Contributors section rendered on the ClawHub skill page:

Quality Gates

Publishing Workflow

1. Contributor opens PR in acaclaw-skills repo
2. AcaClaw team reviews (code, tests, security, compatibility)
3. PR merged → CI publishes to ClawHub under @acaclaw account
4. skills.json updated with new version
5. AcaClaw Hub (acaclaw.com/hub) rebuilt with contributor data

Environment Architecture

Full documentation: Computing Environment

AcaClaw uses Miniforge (conda-forge) to manage Python and R in isolated Conda environments. The design follows three stages:

1. Base Install — Miniforge + Python + core scientific stack in a single acaclaw env
2. Discipline Selection — Must-have packages for chosen disciplines are merged into the base env. R is opt-in.
3. On-Demand Packages — New packages are installed into the default env first. Only on conflict, a new auxiliary env is created and registered.

Environments

Environment Compatibility Rules

• One primary environment (acaclaw) with all disciplines merged — no duplication
• R is opt-in — not installed by default
• New packages try the default env first; auxiliary envs created only on conflict
• All envs are registered in ~/.acaclaw/config/env-manifest.json and injected into LLM context
• Miniforge (conda-forge) handles cross-language dependency resolution between Python and R
• See Computing Environment for the full cascade resolution design

Data Safety Architecture

Full documentation: Data Safety

Research data is irreplaceable. AcaClaw builds a two-layer data protection system on top of OpenClaw’s infrastructure:

Key Safety Guarantees

See Data Safety for the complete design including trash system, workspace snapshots, git compatibility, retention policies, and configuration reference.

UI Strategy: Patched OpenClaw UI vs Separate Plugin UI

The Core Question

AcaClaw needs a research-focused web interface. OpenClaw already ships a web UI (the Control UI). Two approaches:

Neither approach modifies OpenClaw’s core source. Strategy A patches the built UI output; Strategy B ignores it entirely.

Strategy A: Patch OpenClaw’s UI

Apply a thin layer of changes on top of OpenClaw’s Control UI: swap the color theme, hide tabs irrelevant to researchers (e.g., developer-facing channel config), add a few AcaClaw-specific tabs (workspace, backup, environment).

What seems attractive:

• Very little code to write — a theme override, a tab filter, a few new route components
• Users get OpenClaw’s existing chat interface, settings, model picker out of the box
• No need to rebuild the entire UI from scratch

What goes wrong:

Verdict: Looks cheap, but the maintenance cost is proportional to OpenClaw’s release frequency, not to the size of AcaClaw’s patches. A one-line theme override still breaks when the CSS variable it targets gets renamed.

Strategy B: Separate Plugin UI (Current — Recommended)

AcaClaw ships its own SPA, built independently. The acaclaw-ui plugin registers HTTP routes in the gateway to serve this SPA at /. OpenClaw’s Control UI is disabled by default.

┌─────────────────────────────────────────────────────────┐
│  OpenClaw Gateway (single process, single port :18789)   │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │ WebSocket RPC │  │ REST API     │  │ Auth + TLS    │ │
│  │ (chat, tools, │  │ (/health,    │  │ (device keys, │ │
│  │  sessions)    │  │  /v1/models) │  │  challenges)  │ │
│  └──────┬───────┘  └──────┬───────┘  └───────┬───────┘ │
│         │                 │                   │          │
│  ┌──────┴─────────────────┴───────────────────┴───────┐ │
│  │             Plugin HTTP Route Pipeline              │ │
│  │                                                     │ │
│  │  acaclaw-ui plugin:                                 │ │
│  │    "/" (exact)     → serves AcaClaw SPA index.html  │ │
│  │    "/assets/*"     → serves built JS/CSS            │ │
│  │    "/chat/*" etc.  → SPA fallback to index.html     │ │
│  └─────────────────────────────────────────────────────┘ │
│                                                          │
│  OpenClaw Control UI: disabled (gateway.controlUi: false)│
└─────────────────────────────────────────────────────────┘

Verdict: More upfront work, but zero ongoing UI maintenance per OpenClaw release.

Head-to-Head

The key insight: The amount of AcaClaw’s UI code is irrelevant to the maintenance cost. What matters is the stability of the contract you depend on. Patching depends on OpenClaw’s internal UI (unstable, changes every release). The plugin approach depends on registerHttpRoute() (stable SDK API, versioned).

OpenClaw Control UI Behavior

By default, AcaClaw’s installer sets:

{
  "gateway": {
    "controlUi": {
      "enabled": false
    }
  }
}

This disables OpenClaw’s built-in UI. AcaClaw’s plugin UI takes over at /. The gateway, RPC, auth, and all backend functionality remain fully operational.

To re-enable for debugging or advanced use:

openclaw config set gateway.controlUi.enabled true
# OpenClaw UI is now available at its base path (default: /openclaw/)
# AcaClaw UI remains at /

Integration Points with OpenClaw

AcaClaw ONLY uses these official OpenClaw APIs:

If OpenClaw doesn’t provide an API for something, AcaClaw Does. Not. Do. It.