Computing Environment

Design Principle: Minimal by default. Install only what you need, when you need it. Conflicts create new environments automatically — never break a working setup.

Overview

AcaClaw uses Miniforge (conda-forge) to manage Python, R, and system-level scientific tools in isolated Conda environments.

Why Miniforge?

Three-Stage Install

AcaClaw installs progressively — each stage is independent and optional beyond Stage 1.

Stage 1          Stage 2               Stage 3
Base Install     Discipline Packages   On-Demand Packages
─────────────    ───────────────────   ──────────────────
Miniforge        bioclaw               User requests
Python 3.12      chemclaw              "install seaborn"
bash tools       medclaw               ↓
core stack       sciclaw               Try default env
                 (R optional)          ↓ conflict?
                                       Create new env

Stage 1: Base Install

Every AcaClaw installation starts here. This is the default environment (acaclaw).

What gets installed:

What is NOT installed by default:

• R (opt-in at Stage 2 or later)
• Discipline-specific packages (Stage 2)
• Deep learning frameworks
• LaTeX / TeX Live

Conda environment name: acaclaw

# Created by the installer
conda create -n acaclaw -c conda-forge python=3.12 numpy scipy pandas ...

This is the primary environment — all commands default to running here.

Stage 2: Discipline Environments

After base install, users choose one or more disciplines. Each discipline adds a focused set of must-have packages to the base environment.

Available Disciplines

R Support

R is not installed in the conda environment by default. AcaClaw uses a hybrid approach that detects and leverages existing system R installations while offering an optional conda R install.

How R detection works:

1. The Environment tab checks for R packages from the active conda environment first
2. If no conda R is found, it checks for a system R installation (/usr/bin/R or R on PATH)
3. If system R is found, its packages are displayed with a “Using system R” banner

System R vs Conda R:

Installing R into the conda environment:

Users can install R into the active conda environment at any time — either from the UI or CLI:

• UI: Click “Install R into conda env” in the Environment tab (shown in the system R banner or the “R Not Installed” card)
• CLI: conda install -n acaclaw -y -c conda-forge r-base r-irkernel r-essentials

The following R packages are installed:

When a user selects a discipline that includes R (Biology, Medicine), discipline-specific R packages are also added (e.g., r-biocmanager for biology, r-survival for medicine).

Single Discipline

When a user picks one discipline, its packages are added to the base acaclaw environment:

# User picks "Biology" + R
conda install -n acaclaw biopython scikit-bio r-base r-irkernel r-essentials r-biocmanager

The environment stays named acaclaw. No new env is created.

Multiple Disciplines

When a user picks multiple disciplines (e.g., Biology + Medicine), all selected packages are merged into the base acaclaw environment:

# User picks Biology + Medicine + R
conda install -n acaclaw \
  biopython scikit-bio \
  lifelines pydicom \
  r-base r-irkernel r-essentials r-biocmanager r-survival

Conda resolves overlapping dependencies automatically. The environment remains acaclaw — one env, all disciplines merged.

“Must-Have” Package Philosophy

Each discipline includes only packages that are:

1. Essential — the discipline cannot function without them
2. Stable — well-maintained, compatible with the base stack
3. Small — minimal footprint (no 4GB frameworks in base)

Everything else is available on-demand (Stage 3).

Stage 3: On-Demand Package Installation

When a user (or the AI agent) needs a package that is not in the current environment, the system follows a cascade resolution strategy.

Resolution Flow

User: "Install seaborn"
         │
         ▼
┌─ Step 1: Try default env (acaclaw) ───────────┐
│  conda install --dry-run -n acaclaw seaborn    │
│  ↓                                             │
│  No conflict? → Install here. Done.            │
│  Conflict?    → Go to Step 2.                  │
└────────────────────────────────────────────────┘
         │ conflict
         ▼
┌─ Step 2: Try existing auxiliary envs ─────────┐
│  For each registered aux env:                  │
│    conda install --dry-run -n <aux> seaborn    │
│    No conflict? → Install here. Done.          │
│  All conflict?  → Go to Step 3.               │
└────────────────────────────────────────────────┘
         │ all conflict
         ▼
┌─ Step 3: Ask user to create new env ──────────┐
│  "seaborn conflicts with your current envs.    │
│   Create a new environment for it?"            │
│                                                │
│  User confirms → conda create -n <name> ...    │
│  Register new env in config + manifest.        │
│  Inform LLM about new env and its purpose.     │
└────────────────────────────────────────────────┘

Why This Order?

New Environment Registration

When a new env is created, the system:

1. Creates the Conda env with the requested package + compatible base packages
2. Writes to config — updates ~/.acaclaw/config/env-manifest.json:

{
  "environments": {
    "acaclaw": {
      "type": "primary",
      "description": "Base scientific environment + Biology + Medicine",
      "pythonVersion": "3.12.8",
      "rVersion": "4.4.1"
    },
    "acaclaw-gpu": {
      "type": "auxiliary",
      "description": "GPU-accelerated computing (PyTorch, CUDA)",
      "pythonVersion": "3.12.8",
      "createdAt": "2026-03-14T10:30:00Z",
      "createdReason": "PyTorch CUDA conflicts with numpy 1.x in primary env"
    }
  },
  "defaultEnv": "acaclaw"
}

1. Updates LLM context — the @acaclaw/academic-env plugin reads the manifest and injects all envs into the system prompt:

## Computing Environments

Primary: `acaclaw` (Python 3.12, R 4.4, Biology + Medicine packages)
Auxiliary: `acaclaw-gpu` (PyTorch + CUDA — use for deep learning tasks)

Use the primary env for general tasks. Switch to acaclaw-gpu when
the user needs GPU computing or deep learning.

1. Registers auto-activation rules — the plugin prefixes commands with the correct conda run -n <env> based on what packages the command needs.

Cascade Example

Day 1: User installs AcaClaw
  → acaclaw env: Python, numpy, scipy, pandas, matplotlib

Day 2: User picks Biology discipline
  → acaclaw env: + biopython, scikit-bio

Day 5: User says "install seaborn"
  → Try acaclaw: no conflict → installed in acaclaw ✓

Day 8: User says "install pytorch with CUDA"
  → Try acaclaw: conflict (CUDA toolkit vs system libs)
  → No aux envs exist yet
  → Ask user: "Create new env for GPU computing?"
  → User confirms → create acaclaw-gpu
  → Register in manifest, inform LLM

Day 10: User says "install torchvision"
  → Try acaclaw: conflict
  → Try acaclaw-gpu: no conflict → installed in acaclaw-gpu ✓

Day 15: User says "install jax[cuda]"
  → Try acaclaw: conflict
  → Try acaclaw-gpu: conflict (JAX CUDA vs PyTorch CUDA)
  → Ask user: "Create new env for JAX?"
  → User confirms → create acaclaw-jax

Environment Auto-Activation

The @acaclaw/academic-env plugin handles environment activation transparently.

How It Works

1. Default: All bash/exec tool calls are prefixed with conda run -n acaclaw
2. Routing: If a command references a package only available in an aux env, the plugin routes it there
3. Explicit: Users can always specify: conda run -n acaclaw-gpu python train.py

Routing Rules

The LLM knows which packages are in which env and uses the correct one.

Directory Layout

~/.acaclaw/
├── miniforge3/              # Miniforge installation
│   ├── bin/
│   │   ├── conda
│   │   ├── mamba
│   │   └── python           # base Python (not used directly)
│   └── envs/
│       ├── acaclaw/          # Primary environment
│       ├── acaclaw-gpu/      # Aux env (user-created)
│       └── ...
├── config/
│   ├── profile.txt           # Selected discipline(s)
│   ├── conda-prefix.txt      # Path to conda installation used
│   ├── env-manifest.json     # All envs, descriptions, metadata
│   └── security-mode.txt     # Standard or Maximum
└── backups/
    └── ...

Conda Environment Definitions

Environment YAML files live in env/conda/ in the AcaClaw repo. They define the base and discipline add-on packages.

Discipline files list only the discipline-specific packages. The installer merges them with the base at install time.

Package Conflict Detection

Before installing any package, the system runs a dry-run to detect conflicts:

conda install --dry-run -n <env> <package> 2>&1

The system never installs a package that would break an existing environment.

CLI Commands

The @acaclaw/academic-env plugin exposes these commands:

# Show all environments and their status
openclaw acaclaw-env status

# List packages in the primary environment
openclaw acaclaw-env packages

# List packages in a specific environment
openclaw acaclaw-env packages --env acaclaw-gpu

# List available disciplines
openclaw acaclaw-env disciplines

# Add a discipline to the primary environment
openclaw acaclaw-env add-discipline biology

# Install a package (uses cascade resolution)
openclaw acaclaw-env install <package>

# Create a new auxiliary environment
openclaw acaclaw-env create-env <name> --description "Purpose of this env"

# Show all registered environments
openclaw acaclaw-env list-envs

Design Rationale

Why Not Separate Envs Per Discipline?

Previous design created a separate env for each discipline (acaclaw-bio, acaclaw-chem, etc.). Problems:

New design: one primary env, discipline packages merged in. Aux envs only on conflict.

Why Not Pre-Install R?

R is opt-in: the Environment tab detects system R automatically and offers a one-click install into the conda environment when isolation is preferred.

Why Cascade Resolution?

Cascade: try default → try aux → ask user. Best of all worlds.

Why Miniforge Over Alternatives?

Miniforge (conda-forge) is the only option that handles Python + R + C deps in a single, license-free environment manager.

Integration with OpenClaw

AcaClaw runs on top of OpenClaw. Understanding how OpenClaw handles Python execution is critical to getting the environment integration right.

How OpenClaw Executes Commands

OpenClaw can run commands in two modes:

What OpenClaw Does NOT Do

• Does not detect conda, venv, pyenv, or any Python environment manager
• Does not activate virtual environments
• Does not pass CONDA_PREFIX, VIRTUAL_ENV, or PYENV_VERSION to sandbox containers
• Does not manage Python packages
• Does not know which packages are installed

How AcaClaw Bridges the Gap

AcaClaw uses three OpenClaw integration points to make Miniforge environments work transparently:

1. before_tool_call Hook — Command Wrapping

The @acaclaw/academic-env plugin intercepts every bash/exec tool call and prefixes it with conda run:

User says: "Run my analysis"
LLM generates: python analysis.py
Plugin rewrites to: conda run --no-banner -n acaclaw python analysis.py

This works because:

• conda run does not require conda activate — no shell profile changes needed
• The conda binary is found via absolute path (~/.acaclaw/miniforge3/bin/conda)
• Gateway mode only — in sandbox mode, the host’s conda binary does not exist inside the container (see Sandbox Mode below)

2. tools.exec.pathPrepend — PATH Configuration

In gateway mode, AcaClaw configures OpenClaw to prepend the Miniforge bin directory to PATH:

{
  "tools": {
    "exec": {
      "pathPrepend": ["~/.acaclaw/miniforge3/bin"]
    }
  }
}

This ensures conda and mamba commands are always available in gateway mode, even without shell profile initialization.

Note: In sandbox mode, this host path does not exist inside the container. Sandbox requires a different approach — see Sandbox Mode below.

3. before_prompt_build Hook — LLM Context

The plugin injects a “Computing Environment” section into the system prompt, telling the LLM:

• Which environments exist and what they contain
• Which packages are available (no need to install)
• When to use which environment (primary vs auxiliary)
• Not to run pip install, conda install, or install.packages() unless explicitly asked

Existing Environment Detection

At startup, the @acaclaw/academic-env plugin probes for existing environments:

1. Check ~/.acaclaw/miniforge3/bin/conda (AcaClaw's own Miniforge)
2. Check ~/.acaclaw/miniforge3/condabin/conda (alternate path)
3. Check system PATH for conda (user's existing Miniforge/Anaconda/Miniconda)
4. If found: query 'conda env list --json' to discover all envs
5. Read ~/.acaclaw/config/env-manifest.json for registered AcaClaw envs
6. Merge: report all discovered envs to the LLM

Reuse policy: If the user already has a working Miniforge or conda installation, AcaClaw can use it instead of installing a second copy. The installer checks for existing conda at:

If an existing conda is found, the installer asks:

Found existing conda at ~/miniforge3 (Miniforge 24.3.0).
  1) Use existing conda installation (recommended if compatible)
  2) Install AcaClaw's own Miniforge at ~/.acaclaw/miniforge3

The acaclaw environment is always created fresh in whichever conda is selected.

Sandbox Mode Considerations

When OpenClaw runs in sandbox (Docker) mode, the host’s Miniforge is not accessible. Sandbox containers are fully isolated:

• Network: none by default — no internet access, so curl/wget cannot download packages
• Root filesystem: read-only by default — cannot install software to /opt, /usr, etc.
• Writable locations: only /tmp, /var/tmp, /run (tmpfs) and the mounted /workspace
• Host paths: only the project workspace is mounted; ~/.acaclaw/miniforge3 is not visible
• Env vars: host environment is not inherited; only explicitly configured vars are passed

There are three strategies for making conda available in sandbox mode:

Strategy 1: Bind-mount host Miniforge (recommended)

Mount the host’s Miniforge installation read-only into the container:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "binds": [
            "~/.acaclaw/miniforge3:/opt/miniforge3:ro"
          ],
          "env": {
            "PATH": "/opt/miniforge3/envs/acaclaw/bin:/opt/miniforge3/bin:/usr/local/bin:/usr/bin:/bin"
          }
        }
      }
    }
  }
}

This is fast (no install step), consistent with the host environment, and works offline. Requires dangerouslyAllowExternalBindSources: true since the source path is outside the workspace.

Strategy 2: Custom Docker image with Miniforge pre-installed

Build a sandbox image that includes Miniforge and the acaclaw environment:

FROM openclaw-sandbox:bookworm-slim
RUN curl -fsSL https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-$(uname -m).sh -o /tmp/mf.sh \
    && bash /tmp/mf.sh -b -p /opt/miniforge3 \
    && rm /tmp/mf.sh
COPY environment.yml /tmp/environment.yml
RUN /opt/miniforge3/bin/conda env create -f /tmp/environment.yml
ENV PATH="/opt/miniforge3/envs/acaclaw/bin:/opt/miniforge3/bin:$PATH"

Then configure OpenClaw to use the custom image:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "image": "acaclaw-sandbox:latest"
        }
      }
    }
  }
}

This is the most robust approach for teams, but requires rebuilding the image when packages change.

Strategy 3: setupCommand (requires network + writable root)

Install Miniforge inside the container at creation time. This requires overriding the default sandbox security settings:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "network": "bridge",
          "readOnlyRoot": false,
          "setupCommand": "curl -fsSL https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-$(uname -m).sh -o /tmp/mf.sh && bash /tmp/mf.sh -b -p /opt/miniforge3 && /opt/miniforge3/bin/conda env create -f /workspace/.acaclaw/environment.yml",
          "env": {
            "PATH": "/opt/miniforge3/envs/acaclaw/bin:/opt/miniforge3/bin:/usr/local/bin:/usr/bin:/bin"
          }
        }
      }
    }
  }
}

Warning: This weakens sandbox security by enabling network access and a writable root filesystem. It is also slow — Miniforge download + env creation runs on every new container. Prefer Strategy 1 or 2.

Configuration Files Written by AcaClaw