ClawMongo -- OpenClaw, but it remembers.

OpenClaw is a personal AI assistant you run on your own devices. It answers you on the channels you already use. It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

ClawMongo is OpenClaw (329K+ stars, 22 messaging channels, native apps, 78 extensions) with its memory replaced by a production MongoDB backend. Where OpenClaw defaults to QMD (SQLite + Markdown files), ClawMongo uses MongoDB Community + mongot + Voyage AI for vector search, knowledge graphs, episode materialization, event-sourcing, and 8 retrieval paths -- all in one database. Nothing is ever lost.

Supported channels include: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, QQ, WebChat.

Website · Docs · Vision · DeepWiki · Getting Started · Updating · Showcase · FAQ · Onboarding · Nix · Docker · Discord

New install? Start here: Getting started

Preferred setup: run openclaw onboard in your terminal. OpenClaw Onboard guides you step by step through setting up the gateway, workspace, channels, and skills. It is the recommended CLI setup path and works on macOS, Linux, and Windows (via WSL2; strongly recommended). Works with npm, pnpm, or bun.

What Is ClawMongo?

The full OpenClaw personal AI assistant -- 22 messaging channels (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Matrix, and 14 more), 78 extensions (25+ LLM providers, tools, media, infra), companion apps for macOS/iOS/Android, voice wake, live canvas, and the entire skills platform -- with a MongoDB brain instead of files.

ClawMongo is not a memory library. It is a complete personal AI assistant with a real database behind it. The product is the assistant. MongoDB is what makes it production-ready.

Who is this for:

1. OpenClaw users whose agent forgot something important. Again. You want a real backend, not files.
2. MongoDB developers who want a personal AI assistant that stores everything in the database you already know and operate.
3. Teams building Company OS -- multi-agent systems that need shared memory, knowledge bases, audit trails, and enterprise-grade isolation. All in MongoDB.

---

Why MongoDB for Agent Memory?

MongoDB is uniquely suited for agent memory because it combines document flexibility, vector search, full-text search, graph traversal, and operational guarantees in a single platform. No other database offers all of these without bolting on external services.

ClawMongo uses 26 MongoDB capabilities. Each one solves a specific agent memory problem:

#	Capability	Why It Matters	How It Works
1	Automated Embeddings	No application-side embedding code, no batch jobs, no model version management	mongot calls Voyage AI API at index time and query time via autoEmbed
2	Vector Search	Semantic recall over conversation history and knowledge base	$vectorSearch with HNSW indexing on voyage-4-large (1024 dimensions)
3	Full-Text Search	Keyword recall when the user asks for exact terms	mongot text indexes with Lucene standard analyzer
4	Hybrid Search	Neither vector nor keyword alone is sufficient for agent memory	$rankFusion / $scoreFusion (MongoDB 8.0+/8.2+), with manual RRF fallback
5	Knowledge Graph	Agents need to traverse relationships, not just match strings	$graphLookup with bi-directional expansion via $facet
6	Event-Sourcing	Every write must be auditable and replayable	Canonical events collection with derived projections (chunks, entities, episodes)
7	Schema Validation	Garbage in, garbage out -- agent memory must be structurally consistent	JSON Schema ($jsonSchema) on all 18 validated collections
8	Change Streams	Multiple gateway instances must stay in sync	Real-time cross-instance notification via MongoDB change streams
9	TTL Indexes	Embedding caches and telemetry data should expire automatically	expireAfterSeconds on embedding_cache, relevance_runs, relevance_artifacts
10	Multi-Tenant Isolation	One database, many agents, zero data leakage	Compound indexes with agentId prefix + $graphLookup restrictSearchWithMatch
11	Idempotent Upserts	Network retries and replays must not corrupt memory	$setOnInsert for creation-time fields + $set for mutable fields on unique compound keys
12	Relevance Telemetry	You cannot improve retrieval quality without measuring it	explain-driven diagnostics across relevance_runs, relevance_artifacts, relevance_regressions
13	Semantic Query Cache	Identical or near-identical queries skip the full retrieval pipeline	SHA-256 exact match + $vectorSearch cosine >= 0.95, per-document TTL, fire-and-forget writes
14	Time Series Telemetry	Operational visibility into every memory operation with automatic retention	Time series collection with granularity: "seconds", P50/P95/P99 latency, cache hit rates
15	Profile Synthesis	Dynamic agent profile from structured memory, entities, episodes, and events	$facet + $lookup aggregation across 5 collections, ~5-50ms
16	Cross-Encoder Re-ranking	Voyage rerank-2.5 precision pass on search results with instruction-following	Two-stage: $vectorSearch recall then rerank-2.5 precision, 8-11% accuracy boost with instructions
17	Query Rewriting	Synonym expansion for improved vector search recall on terse queries	Deterministic abbreviation + synonym expansion before embedding, planner sees original query
18	Pluggable Entity Extraction	Regex default with LLM upgrade path for richer knowledge graphs	EntityExtractor interface, RegexEntityExtractor + LLMEntityExtractor with timeout + fallback
19	Mutation Audit Trail	Every memory write tracked with before/after snapshots	memory_mutations collection, fire-and-forget recordMutation, 90-day TTL auto-cleanup
20	Status Lifecycle	Episodes and chunks have active/archived/deleted states	status field + { $ne: "deleted" } filter on all query paths (backward compatible with existing data)
21	Procedural Memory Evolution	Procedures track version history, success/fail counts	Atomic $inc counters + $push with $slice: -20 for bounded evolution history
22	Conservative Graph Deletion	Conflict detection prevents accidental data loss in knowledge graphs	Relation count check before delete, force override, audit trail on every deletion
23	Working Memory Bounds	Configurable session event capacity for context window management	$sort + $limit optimization (MongoDB coalesces adjacent stages), default 50 events
24	Temporal Grounding	Entity extraction captures dates and times as first-class concepts	DATE_REGEX patterns + extractedAt timestamps on entities, dates stored as type "concept"
25	Role-Based Extraction	Separate extraction prompts for user vs assistant messages	buildUserExtractionPrompt / buildAssistantExtractionPrompt + sourceRole tracking on entities
26	Tiered Retrieval	IDs-only projection mode for 10x token reduction in large memory spaces	$project after $vectorSearch returns lightweight results, full content fetched on demand

For the full technical deep-dive on each capability with code examples: MongoDB Capabilities in ClawMongo

---

ClawMongo vs Default OpenClaw Memory

Capability	OpenClaw Default (QMD/SQLite)	ClawMongo (MongoDB)
Storage backend	SQLite file + Markdown files	MongoDB Community (replica set)
Vector search	sqlite-vec or LanceDB	mongot + Voyage AI autoEmbed
Embedding management	Application-side (multiple providers)	Automated via mongot (zero app code)
Full-text search	SQLite FTS5 / BM25	mongot text indexes (Lucene)
Hybrid search	BM25 + vector with MMR	$rankFusion / $scoreFusion + RRF
Knowledge graph	None	$graphLookup with entities + relations
Episodes	None	Auto-materialized from event windows
Event sourcing	None (append-only Markdown)	Canonical events collection
Structured memory	Basic key-value	Salience, temporal validity, state, provenance
Procedures	None	Versioned workflow artifacts
Retrieval paths	1 (search)	8 paths with planner-driven selection
Schema validation	None	JSON Schema on all collections
Multi-tenant isolation	Filesystem separation	Compound indexes with agentId prefix
Operational visibility	Limited	Ingest runs, projection runs, relevance telemetry, time series observability
Query caching	None	Two-tier semantic cache (SHA-256 exact + cosine similarity)
Data model	Flat files + SQLite rows	23 collections, 66 indexes + 9 search indexes

Decision rule: If your workload is one user with small memory files, OpenClaw's default memory is fine. If you need retrieval quality SLOs, operational visibility, knowledge graphs, or team-scale agent memory, ClawMongo is the practical path.

Full comparison with migration guidance: ClawMongo vs Default Memory

---

MongoDB Memory Architecture

ClawMongo uses a canonical-truth-first architecture where events are the single source of truth. Everything else -- chunks, entities, relations, episodes, procedures -- is derived.

Write Path:
  Message / tool output -> writeEventAndProject()
                           +-> events       (canonical, append-only)
                           +-> chunks       (projected, searchable)
                           +-> ingest_runs  (operational audit)
                           +-> extractAndUpsertEntities(role)
                                +-> entities   (@mentions, #tags, URLs, dates, quoted names)
                                +-> relations  (links between entities, weighted)
                                +-> memory_mutations (before/after snapshots, 90-day TTL)
                           +-> checkAutoEpisodeTriggers()
                                +-> episodes   (materialized, status lifecycle)

Retrieval Path:
  Query -> checkCache() -> HIT? return cached results
                        -> MISS -> planRetrieval() -> score 8 paths by keyword heuristics
           +-> active-critical  (high-salience recent)
           +-> structured       (facts, preferences)
           +-> episodic         (summarized threads, status-filtered)
           +-> graph            ($graphLookup, conservative delete)
           +-> kb               (knowledge base docs)
           +-> hybrid           ($rankFusion vector+text)
           +-> raw-window       (bounded working memory, $sort+$limit)
           +-> procedural       (versioned workflows, success tracking)
           -> crossEncoderRerank() -> deduplicate -> writeCache() -> return to agent

Observability:
  All paths emit to memory_telemetry (time series, fire-and-forget, 7-day TTL)

23 Collections

Group	Collections
Conversation memory	chunks, files, embedding_cache, meta
Knowledge base	knowledge_base, kb_chunks
Structured memory	structured_mem, structured_mem_revisions
Procedures	procedures, procedure_revisions
Relevance telemetry	relevance_runs, relevance_artifacts, relevance_regressions
v2 event system	events, entities, relations, entity_links, episodes
Operational	ingest_runs, projection_runs
Query cache	query_cache
Audit trail	memory_mutations (90-day TTL)
Observability	memory_telemetry (time series)

All backed by 66 standard indexes and up to 9 MongoDB Search indexes (4 text + 5 vector autoEmbed). Reranking via Voyage rerank-2.5 enabled by default (2s timeout, graceful fallback).

8 Retrieval Paths

The retrieval planner (planRetrieval) scores paths based on query analysis:

Path	When It Scores High
active-critical	Current-state, crisis, blocker, or "what matters now" queries
procedural	Workflow, runbook, process, or exact learned procedure lookups
structured	Fact, preference, or current-truth lookups
raw-window	Recent context ("what did I just say")
graph	Entity names detected in query
episodic	Time-range or summary queries
kb	Reference material queries
hybrid	Broad lexical + vector fallback

After retrieval, crossEncoderRerank (Voyage rerank-2.5, on by default) applies cross-encoder precision scoring with a 2-second timeout and graceful fallback, followed by rerankResults for source diversity, episode boost, deduplication, and backstop execution.

MongoDB Memory Tooling

ClawMongo now exposes a richer MongoDB-first memory tool surface instead of forcing every recall question through generic search:

• searchMode: auto, direct, or agentic
• ordered sourcePreference
• bounded timeRange
• needExactEvidence
• bounded maxPasses
• planner-visible metadata: classification, passes, queries tried, constraints, rejected evidence, and executed paths
• memory_active_slate: current-state, blockers, and what matters now
• memory_discovery_projection: change reports, contradiction checks, topic briefs, and entity briefs
• memory_context_bundle: prompt-ready, token-bounded handoff and briefing context

The important behavior change is selective, not universal:

• exact lookups stay single-pass and cache-fast
• family, comparison, scoped, and temporal lookups can expand across bounded extra passes
• hard constraints stay enforced near MongoDB instead of being treated like prompt suggestions
• exact evidence remains first-class for auditability and answer discipline
• handoff-style questions no longer need the agent to manually stitch together search hits and recent transcript context

This is validated in the real production-readiness and runtime-write suites against mongodb/mongodb-atlas-local:preview, including direct-vs-agentic memory_search, exact procedural backstops, prompt-ready context bundle assembly, and current-state recall via active slate.

Test Coverage

• ~300 v2 memory unit tests
• 1000+ total memory tests across 59 test files
• 90 live e2e tests against real MongoDB 8.2 + Voyage AI (production-readiness suite)

---

Quick Start

Prerequisites: Node.js 22+ (24 recommended), Docker (for mongodb-atlas-local:preview), Voyage AI API key, an LLM API key (Anthropic Claude recommended).

# Start MongoDB (atlas-local:preview -- bundles mongod + mongot + search)
./docker/mongodb/start-preview.sh

npm install -g @romiluz/clawmongo@latest

clawmongo onboard --install-daemon

For Docker-based MongoDB setup, detailed configuration, and verification steps: Getting Started with ClawMongo

openclaw is shipped as an alias to clawmongo for compatibility.

---

For Agents: Install ClawMongo

If you are an AI agent (Claude, GPT, Cursor, Windsurf, etc.) helping a user set up ClawMongo, follow these steps exactly:

Prerequisites Check

node --version        # Must be 22+ (24 recommended)
docker --version      # Docker Desktop must be installed and running

Step 1: Start MongoDB (atlas-local:preview)

# Set Voyage AI API key (required for automated embeddings)
export VOYAGE_API_KEY="pa-..."

# Start the single-container MongoDB stack
# This bundles mongod + mongot + Atlas Search + Vector Search + auto-embeddings
./docker/mongodb/start-preview.sh

# Verify it's healthy
docker inspect --format='{{.State.Health.Status}}' clawmongo-preview
# Expected: "healthy"

Critical: Use the :preview tag only. The :latest, :8.0, and :8.2 tags do NOT include the community mongot with Voyage AI auto-embeddings.

Step 2: Install ClawMongo

npm install -g @romiluz/clawmongo@latest
clawmongo --version

Step 3: Run Onboarding

clawmongo onboard --install-daemon

The wizard will:

1. Prompt for Voyage AI API key (if not already set)
2. Auto-detect the atlas-local Docker container
3. Verify MongoDB topology (mongod + mongot)
4. Bootstrap 23 collections + 66 indexes + 9 search indexes
5. Configure LLM provider (Anthropic Claude recommended)
6. Optionally import knowledge base documents

Step 4: Verify

clawmongo doctor                    # Check MongoDB + mongot + Voyage AI
clawmongo channels status --probe   # Check channel connectivity
clawmongo agent --message "Hello, remember my name is Alice" --thinking low
clawmongo agent --message "What is my name?" --thinking low

Step 5: Connect a Channel (Optional)

# Telegram (quickest)
clawmongo config set channels.telegram.botToken "YOUR_BOT_TOKEN"
clawmongo gateway restart

Troubleshooting

Symptom	Fix
Connection refused on port 27017	Run ./docker/mongodb/start-preview.sh
mongot not detected	Ensure you're using mongodb-atlas-local:preview (not :latest)
VOYAGE_API_KEY not set	export VOYAGE_API_KEY=pa-... then restart the Docker container
Vector search returns empty	Wait 30s for auto-embedding indexing to complete

Configuration Reference

Minimal ~/.openclaw/openclaw.json:

{
  "agent": { "model": "anthropic/claude-opus-4-6" },
  "memory": {
    "mongodb": {
      "uri": "mongodb://localhost:27017/openclaw?directConnection=true",
      "embeddingMode": "automated"
    }
  }
}

---

The Full OpenClaw Platform

ClawMongo inherits the entire OpenClaw platform. Everything below works identically.

22 Messaging Channels

WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Google Chat, Signal, BlueBubbles (iMessage), iMessage (legacy), IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WebChat.

Full channel setup guides: OpenClaw Docs -- Channels

78 Extensions

• 22 messaging channels + 2 transport plugins (voice call, device pairing)
• 25+ LLM provider plugins (OpenAI, Anthropic, Google, Bedrock, Mistral, Ollama, OpenRouter, and more)
• Tool plugins (Brave search, Firecrawl, Tavily, browser control)
• Media plugins (ElevenLabs speech, Microsoft speech)
• Infrastructure plugins (OpenTelemetry, sandbox backends, MCP bridge)

Companion Apps

• macOS -- menu bar control, Voice Wake, push-to-talk, Canvas, WebChat
• iOS -- Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing
• Android -- chat sessions, voice tab, Canvas, camera, SMS/contacts/calendar access

Tools and Automation

• Browser control -- dedicated Chrome/Chromium with CDP
• Live Canvas + A2UI -- agent-driven visual workspace
• Voice Wake + Talk Mode -- macOS/iOS/Android
• Cron jobs, Webhooks, Gmail Pub/Sub
• Skills platform -- bundled, managed, workspace skills

All links above point to the upstream OpenClaw docs. ClawMongo inherits this functionality unchanged.

---

Development and Ops

Install from Source

git clone https://github.com/romiluz13/ClawMongo.git
cd ClawMongo

pnpm install
pnpm ui:build
pnpm build

pnpm clawmongo onboard --install-daemon
pnpm gateway:watch  # dev loop with auto-reload

Keep in Sync with Upstream

pnpm upstream:steady          # routine check -- exits clean if at 0 behind
pnpm upstream:report           # divergence + conflict hotspots before a merge wave
bash scripts/sync-upstream.sh --merge  # merge upstream when ready

Detailed workflow: docs/reference/upstream-sync.md

Development Channels

• stable: tagged releases (vYYYY.M.D), npm dist-tag latest
• beta: prerelease tags (vYYYY.M.D-beta.N), npm dist-tag beta
• dev: moving head of main, npm dist-tag dev

Switch: clawmongo update --channel stable|beta|dev

Security Defaults (DM Access)

ClawMongo connects to real messaging surfaces. Treat inbound DMs as untrusted input.

Default behavior: DM pairing -- unknown senders receive a pairing code. Approve with clawmongo pairing approve <channel> <code>. Public inbound DMs require explicit opt-in (dmPolicy="open").

Full security guide: OpenClaw Docs -- Security

---

Built on OpenClaw

ClawMongo is a fork of OpenClaw, which is supported by these sponsors:

Subscriptions (OAuth):

• OpenAI (ChatGPT/Codex)

Model note: while many providers and models are supported, prefer a current flagship model from the provider you trust and already use. See Onboarding.

Install (recommended)

Runtime: Node 24 (recommended) or Node 22.16+.

npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

openclaw onboard --install-daemon

OpenClaw Onboard installs the Gateway daemon (launchd/systemd user service) so it stays running.

Quick start (TL;DR)

Runtime: Node 24 (recommended) or Node 22.16+.

Full beginner guide (auth, pairing, channels): Getting started

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

# Send a message
openclaw message send --target +1234567890 --message "Hello from OpenClaw"

# Talk to the assistant (optionally deliver back to any connected channel: WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/IRC/Microsoft Teams/Matrix/Feishu/LINE/Mattermost/Nextcloud Talk/Nostr/Synology Chat/Tlon/Twitch/Zalo/Zalo Personal/WeChat/QQ/WebChat)
openclaw agent --message "Ship checklist" --thinking high

Upgrading? Updating guide (and run openclaw doctor).

Models config + CLI: Models. Auth profile rotation + fallbacks: Model failover.

Security defaults (DM access)

OpenClaw connects to real messaging surfaces. Treat inbound DMs as untrusted input.

Full security guide: Security

Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack:

• DM pairing (dmPolicy="pairing" / channels.discord.dmPolicy="pairing" / channels.slack.dmPolicy="pairing"; legacy: channels.discord.dm.policy, channels.slack.dm.policy): unknown senders receive a short pairing code and the bot does not process their message.
• Approve with: openclaw pairing approve <channel> <code> (then the sender is added to a local allowlist store).
• Public inbound DMs require an explicit opt-in: set dmPolicy="open" and include "*" in the channel allowlist (allowFrom / channels.discord.allowFrom / channels.slack.allowFrom; legacy: channels.discord.dm.allowFrom, channels.slack.dm.allowFrom).

Run openclaw doctor to surface risky/misconfigured DM policies.

Highlights

• Local-first Gateway — single control plane for sessions, channels, tools, and events.
• Multi-channel inbox — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, QQ, WebChat, macOS, iOS/Android.
• Multi-agent routing — route inbound channels/accounts/peers to isolated agents (workspaces + per-agent sessions).
• Voice Wake + Talk Mode — wake words on macOS/iOS and continuous voice on Android (ElevenLabs + system TTS fallback).
• Live Canvas — agent-driven visual workspace with A2UI.
• First-class tools — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
• Companion apps — macOS menu bar app + iOS/Android nodes.
• Onboarding + skills — onboarding-driven setup with bundled/managed/workspace skills.

Security model (important)

• Default: tools run on the host for the main session, so the agent has full access when it is just you.
• Group/channel safety: set agents.defaults.sandbox.mode: "non-main" to run non-main sessions inside sandboxes. Docker is the default sandbox backend; SSH and OpenShell backends are also available.
• Typical sandbox default: allow bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn; deny browser, canvas, nodes, cron, discord, gateway.
• Before exposing anything remotely, read Security, Sandboxing, and Configuration.

Operator quick refs

• Chat commands: /status, /new, /reset, /compact, /think <level>, /verbose on|off, /trace on|off, /usage off|tokens|full, /restart, /activation mention|always
• Session tools: sessions_list, sessions_history, sessions_send
• Skills registry: ClawHub
• Architecture overview: Architecture

Docs by goal

• New here: Getting started, Onboarding, Updating
• Channel setup: Channels index, WhatsApp, Telegram, Discord, Slack
• Apps + nodes: macOS, iOS, Android, Nodes
• Config + security: Configuration, Security, Sandboxing
• Remote + web: Gateway, Remote access, Tailscale, Web surfaces
• Tools + automation: Tools, Skills, Cron jobs, Webhooks, Gmail Pub/Sub
• Internals: Architecture, Agent, Session model, Gateway protocol
• Troubleshooting: Channel troubleshooting, Logging, Docs home

Apps (optional)

The Gateway alone delivers a great experience. All apps are optional and add extra features.

If you plan to build/run companion apps, follow the platform runbooks below.

macOS (OpenClaw.app) (optional)

• Menu bar control for the Gateway and health.
• Voice Wake + push-to-talk overlay.
• WebChat + debug tools.
• Remote gateway control over SSH.

Note: signed builds required for macOS permissions to stick across rebuilds (see macOS Permissions).

iOS node (optional)

• Pairs as a node over the Gateway WebSocket (device pairing).
• Voice trigger forwarding + Canvas surface.
• Controlled via openclaw nodes ….

Runbook: iOS connect.

Android node (optional)

• Pairs as a WS node via device pairing (openclaw devices ...).
• Exposes Connect/Chat/Voice tabs plus Canvas, Camera, Screen capture, and Android device command families.
• Runbook: Android connect.

From source (development)

Use pnpm for source checkouts. The repository is a pnpm workspace, and bundled plugins load from extensions/* during development so their package-local dependencies and your edits are used directly. Plain npm install at the repo root is not a supported source setup.

For the dev loop:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install

# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup

# Optional: prebuild Control UI before first startup
pnpm ui:build

# Dev loop (auto-reload on source/config changes)
pnpm gateway:watch

If you need a built dist/ from the checkout (for Node, packaging, or release validation), run:

pnpm build
pnpm ui:build

pnpm openclaw setup writes the local config/workspace needed for pnpm gateway:watch. It is safe to re-run, but you normally only need it on first setup or after resetting local state. pnpm gateway:watch does not rebuild dist/control-ui, so rerun pnpm ui:build after ui/ changes or use pnpm ui:dev when iterating on the Control UI. If you want this checkout to run onboarding directly, use pnpm openclaw onboard --install-daemon.

Note: pnpm openclaw ... runs TypeScript directly (via tsx). pnpm build produces dist/ for running via Node / the packaged openclaw binary, while pnpm gateway:watch rebuilds the runtime on demand during the dev loop.

Development channels

• stable: tagged releases (vYYYY.M.D or vYYYY.M.D-<patch>), npm dist-tag latest.
• beta: prerelease tags (vYYYY.M.D-beta.N), npm dist-tag beta (macOS app may be missing).
• dev: moving head of main, npm dist-tag dev (when published).

Switch channels (git + npm): openclaw update --channel stable|beta|dev. Details: Development channels.

Agent workspace + skills

• Workspace root: ~/.openclaw/workspace (configurable via agents.defaults.workspace).
• Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md.
• Skills: ~/.openclaw/workspace/skills/<skill>/SKILL.md.

Configuration

Minimal ~/.openclaw/openclaw.json (model + defaults):

{
  agent: {
    model: "<provider>/<model-id>",
  },
}

Full configuration reference (all keys + examples).

Star History

Molty

OpenClaw was built for Molty, a space lobster AI assistant. 🦞 by Peter Steinberger and the community.

• openclaw.ai
• soul.md
• steipete.me
• @openclaw

Community

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs.

Special thanks to Mario Zechner for his support and for pi-mono. Special thanks to Adam Doppelt for the lobster.bot domain.

Thanks to all clawtributors: