openclaw-platform

Monorepo-style OpenClaw workspace for local usage + development (git submodule in openclaw/) with modular JSON5 config and optional Docker sandboxes.

• English (this file) · 中文: README.zh-CN.md
• Run everything via pnpm openclaw ... (wrapper: scripts/openclaw.mjs)
• Commit-safe config lives in config/openclaw/ (split into modular JSON5 files)
• Repo-local state lives in bots/ (gitignored; migration notes in bots/README.md)
• Instead of the default ~/.openclaw/, this repo pins state/config/workspaces under bots/ (e.g. bots/workspaces/<agent>/) so everything stays in one place

[!NOTE] You are reading the monorepo branch. If you need the Termux + proot setup and tooling, switch to the proot-debian branch.

[!IMPORTANT] config/.env and bots/ contain secrets/state. Keep them out of git.

This repo intentionally tracks only bots/README.md and bots/openclaw.json under bots/.

What this repo gives you

• A predictable, repo-local OpenClaw setup: config + workspaces + state live together under this repo folder (instead of ~/.openclaw/).
• Modular JSON5 config you can edit/review in git (secrets stay in config/.env, never in JSON5).
• Repo-local plugins (custom tools/skills) under plugins/ that live outside the openclaw/ submodule.
• Optional Docker sandbox images for agents that need extra system dependencies (LibreOffice, OCR, etc.).

Contents

• Prerequisites
• Quick start
• How config is wired
• Repo layout
• Project tree (sketch)
• Docs
• Common commands
• Sandboxed agents (Docker)

Prerequisites

• Node.js 24.x (recommended; OpenClaw requires >=22.12.0)
• corepack enable (for pnpm)
• Docker (optional; only needed for sandboxed agents)

Quick start

git clone --recurse-submodules https://github.com/appautomaton/openclaw-monorepo.git
cd openclaw-monorepo

git submodule update --init --recursive

corepack enable
pnpm openclaw:install
pnpm openclaw:build
pnpm openclaw:ui:build

cp config/.env.template config/.env
# Edit config/.env (never commit it)
# Optional: set EXA_API_KEY if you want the exa-search plugin/tool.

pnpm openclaw models status   # verify config loads (fails fast if env vars missing)
pnpm openclaw gateway

If you are setting up Termux + proot-distro, switch to the proot-debian branch and follow docs/proot-setup.md there.

How config is wired

• Secrets live in config/.env (gitignored; copy from config/.env.template).
• Source config entrypoint is bots/openclaw.json:

{ $include: "../config/openclaw/openclaw.json5" }

• Modular source config lives under config/openclaw/ (JSON5 + $include).
• The wrapper renders that source tree into bots/.runtime/openclaw.runtime.json5 before launch, so OpenClaw writes back to disposable runtime state instead of the tracked source fragments.
• Config can reference env vars via ${ENV_VAR} (missing/empty vars fail fast).
• OPENCLAW_STATE_DIR=bots is supported: scripts/openclaw.mjs treats relative paths as repo-root-relative.

flowchart TD
  A[pnpm openclaw COMMAND] --> B[scripts/openclaw.mjs]
  B --> C[load config/.env]
  B --> D[normalize OPENCLAW_STATE_DIR]
  D --> E[config/openclaw/openclaw.json5]
  E --> F[bots/.runtime/openclaw.runtime.json5]

Repo layout

All paths below are relative to the repo root.

• openclaw/ — OpenClaw submodule (pnpm workspace; build output in openclaw/dist/)
• scripts/ — wrapper entrypoint (see scripts/README.md)
• config/ — versioned config (commit-safe) + config/.env.template
• plugins/ — repo-local OpenClaw plugins (custom tools/skills; see plugins/README.md)
• bots/ — repo-local OpenClaw state dir (gitignored; see bots/README.md)
• dockerfiles/ — Docker build contexts for sandbox images (see dockerfiles/README.md)
• docs/ — extra docs for this repo

Architecture notes: ARCHITECTURE.md

Project tree (sketch)

.
├─ README.md
├─ package.json                  # repo wrapper scripts (pnpm openclaw:*)
├─ .gitmodules                   # pins the OpenClaw submodule
├─ openclaw/                     # OpenClaw submodule (upstream fork)
├─ scripts/
│  ├─ openclaw.mjs               # loads config/.env, normalizes OPENCLAW_STATE_DIR, runs OpenClaw CLI
│  └─ browser-service.sh         # optional helper for the browser sidecar
├─ plugins/                      # repo-local OpenClaw plugins (custom tools/skills)
│  ├─ README.md
│  └─ exa-search/                 # example: Exa Search plugin (tool + skill pack)
├─ config/
│  ├─ .env.template              # copy to config/.env (gitignored) and fill tokens/keys
│  ├─ README.md                  # config wiring notes
│  └─ openclaw/                  # modular JSON5 config (commit-safe; no secrets)
│     ├─ openclaw.json5          # source root JSON5 (uses $include)
│     └─ agents/                 # agent definitions (defaults + per-agent files)
├─ bots/                         # repo-local state dir (gitignored; sensitive)
│  ├─ README.md                  # migration/bootstrap notes (tracked)
│  └─ openclaw.json              # compatibility entrypoint (tracked; source config reference)
├─ dockerfiles/                  # sandbox image build contexts used by sandboxed agents
└─ docs/                         # extra docs for this repo

Docs

• bots/README.md — migrating from an existing ~/.openclaw/ install into repo-local state
• config/README.md — how config/env/state are wired
• docs/COMMANDS.md — command reference for this repo wrapper
• docs/proot-setup.md — Termux + proot-distro setup notes (see proot-debian branch)
• pnpm docs:check — validates onboarding docs against executable repo truth

Common commands

pnpm openclaw models status
pnpm openclaw agents list --bindings
pnpm openclaw channels status --probe
pnpm openclaw hooks list
pnpm openclaw nodes status
pnpm docs:check

Sandboxed agents (Docker)

Only needed if an agent config uses sandbox.docker.image (i.e., you actually enabled Docker sandboxing for that agent). Example: config/openclaw/agents/list/writer.json5 sets "image": "localhost/openclaw-sandbox-writer:bookworm".

docker build -f dockerfiles/writer/Dockerfile -t localhost/openclaw-sandbox-writer:bookworm dockerfiles/writer

See dockerfiles/ and config/openclaw/agents/list/.