Read this README in: English | 中文 | 繁體中文（香港） | 日本語 | 한국어 | Français | Español | Português | Deutsch | Bahasa Melayu | தமிழ்

LalaClaw

A better way to co-create with agents.

Author: Marila Wang

Highlights

• React + Vite command center UI with chat, timeline, inspector, theme, locale, and attachment flows
• VS Code-style file exploration with separate session and workspace trees, preview actions, and richer document handling
• Built-in locale support for 中文, 繁體中文（香港）, English, 日本語, 한국어, Français, Español, Português, Deutsch, Bahasa Melayu, and தமிழ்
• Node.js backend that can connect to local or remote OpenClaw gateways
• Focused tests, CI, linting, contribution docs, and release notes

Product Tour

• Top overview bar for agent, model, fast mode, think mode, context, queue, theme, and locale
• Main chat workspace for prompts, attachments, streaming replies, and session reset
• Inspector panel for timeline, files, artifacts, snapshots, and runtime activity
• Runtime loop that works in mock mode by default and can switch to live OpenClaw gateways

A longer walkthrough lives in docs/en/showcase.md.

Documentation

• Language index: docs/README.md
• English guide: docs/en/documentation.md
• Quick start: docs/en/documentation-quick-start.md
• Interface guide: docs/en/documentation-interface.md
• Sessions and runtime: docs/en/documentation-sessions.md
• Architecture notes: docs/en/architecture.md

More structure notes live in server/README.md and src/features/README.md.

Installation Guide

Install Through OpenClaw

Use OpenClaw to install LalaClaw on a remote Mac or Linux machine, then access it locally through SSH port forwarding.

If you already have a machine with OpenClaw installed and you can log in to that machine over SSH, you can ask OpenClaw to install this project from GitHub, start it on the remote host, and then forward the remote port back to your local computer.

Tell OpenClaw:

Install https://github.com/aliramw/lalaclaw

Typical flow:

1. OpenClaw clones this repository on the remote machine.
2. OpenClaw installs dependencies and starts LalaClaw.
3. The app listens on 127.0.0.1:5678 on the remote machine.
4. You forward that remote port to your local computer over SSH.
5. You open the forwarded local address in your browser.

Example SSH port forwarding:

ssh -N -L 3000:127.0.0.1:5678 root@your-remote-server-ip

Then open the forwarded local address:

http://127.0.0.1:3000

Install From npm

For the simplest end-user setup:

npm install -g lalaclaw@latest
lalaclaw init

Then open http://127.0.0.1:5678.

Notes:

• lalaclaw init writes local config to ~/.config/lalaclaw/.env.local on macOS and Linux
• By default, lalaclaw init uses HOST=127.0.0.1, PORT=5678, and FRONTEND_PORT=4321 unless you override them
• In a source checkout, lalaclaw init starts both Server and Vite Dev Server in the background, then prompts to open the Dev Server URL
• On macOS npm installs, lalaclaw init installs and starts the Server launchd service, then prompts to open the Server URL
• On Linux npm installs, lalaclaw init starts the Server in the background, then prompts to open the Server URL
• Use lalaclaw init --no-background if you only want to write config without auto-starting services
• After --no-background, run lalaclaw doctor, then use lalaclaw dev for source checkouts or lalaclaw start for packaged installs
• lalaclaw status, lalaclaw restart, and lalaclaw stop control the macOS launchd Server service only
• Previewing doc, ppt, and pptx files requires LibreOffice. On macOS, run lalaclaw doctor --fix or brew install --cask libreoffice

Install From GitHub

If you want a source checkout for development or local modification:

git clone https://github.com/aliramw/lalaclaw.git lalaclaw
cd lalaclaw
npm ci
npm run doctor
npm run lalaclaw:init

Then open http://127.0.0.1:4321.

Notes:

• npm run lalaclaw:init starts both Server and Vite Dev Server in the background by default unless you pass --no-background
• After background startup, it prompts to open the Dev Server URL, which defaults to http://127.0.0.1:4321
• If you only want config generation, run npm run lalaclaw:init -- --no-background
• npm run lalaclaw:start runs in the current terminal and stops when that terminal closes
• If you want the live development environment later, run npm run dev:all and open http://127.0.0.1:4321 or your configured FRONTEND_PORT

Update LalaClaw

If you installed LalaClaw with npm and want the newest version:

npm install -g lalaclaw@latest
lalaclaw init

If you want a specific published version instead, such as 2026.3.17-9:

npm install -g [email protected]
lalaclaw init

If you installed LalaClaw from GitHub and want the latest version:

cd /path/to/lalaclaw
git pull
npm ci
npm run build
npm run lalaclaw:start

If you want a specific released version instead, such as 2026.3.17-9:

cd /path/to/lalaclaw
git fetch --tags
git checkout 2026.3.17-9
npm ci
npm run build
npm run lalaclaw:start

Common Commands

• npm run dev:all starts the standard local development workflow
• npm run doctor checks Node.js, OpenClaw discovery, ports, and local config
• npm run lalaclaw:init writes or refreshes local bootstrap config
• npm run lalaclaw:start starts the built app after checking dist/
• npm run build creates the production bundle
• npm test runs the Vitest suite once
• npm run lint runs ESLint across the workspace

For the full command list and contributor workflow, see CONTRIBUTING.md.

Contributing

Contributions are welcome. For larger features, architectural changes, or user-visible behavior changes, please open an issue first.

Before opening a PR:

• Keep changes focused and avoid unrelated refactors
• Add or update tests for behavior changes
• Route new user-facing copy through src/locales/*.js
• Update docs for user-visible behavior changes
• Update CHANGELOG.md when versioned behavior changes

The full contribution checklist lives in CONTRIBUTING.md.

Development Notes

• Use npm run dev:all for the standard local development workflow
• Use http://127.0.0.1:4321 for the Vite app during development by default, or your configured FRONTEND_PORT
• Use npm run lalaclaw:start or npm start only for built output that depends on dist/
• By default, the app auto-detects a local OpenClaw gateway when available
• To force mock mode for reproducible UI or frontend debugging, set COMMANDCENTER_FORCE_MOCK=1
• Before submitting a PR, prefer running npm run lint, npm test, and npm run build

Versioning

LalaClaw uses npm-compatible calendar versioning for releases.

• Update CHANGELOG.md whenever the project version changes
• Use npm-compatible calendar versions. For multiple releases on the same day, use YYYY.M.D-N such as 2026.3.17-9, not YYYY.M.D.N
• Call out breaking changes explicitly in release notes and migration-facing docs
• The repository currently targets Node.js 22 via .nvmrc

OpenClaw Wiring

If ~/.openclaw/openclaw.json exists, LalaClaw automatically detects your local OpenClaw gateway and reuses its loopback endpoint plus gateway token.

For a fresh source checkout, a typical setup looks like this:

git clone https://github.com/aliramw/lalaclaw.git lalaclaw
cd lalaclaw
npm ci
npm run doctor
npm run lalaclaw:init

If you want to point to another OpenClaw-compatible gateway, set:

export OPENCLAW_BASE_URL="https://your-openclaw-gateway"
export OPENCLAW_API_KEY="..."
export OPENCLAW_MODEL="openclaw"
export OPENCLAW_AGENT_ID="main"
export OPENCLAW_API_STYLE="chat"
export OPENCLAW_API_PATH="/v1/chat/completions"

If your gateway is closer to the OpenAI Responses API, use:

export OPENCLAW_API_STYLE="responses"
export OPENCLAW_API_PATH="/v1/responses"

Without these variables, the app runs in mock mode so the UI and chat loop remain usable during bootstrap.