name: openclaw
description: OpenClaw personal assistant gateway WebSocket architecture agent runtime workspace configuration memory system skills loading AGENTS.md SOUL.md USER.md IDENTITY.md BOOT.md BOOTSTRAP.md session management channel routing macOS setup permissions TCC iMessage WhatsApp Telegram Discord Signal Slack CLI commands hooks system browser automation vector search pairing authentication credentials configuration troubleshooting doctor command multi-agent support formal verification security model providers queue streaming compaction context management

OpenClaw

OpenClaw is a personal AI assistant system with a gateway-centric architecture that manages messaging channels, agents, workspace configuration, memory, and skills. It runs on macOS (primary), Linux, and Docker, providing a powerful runtime for multi-agent AI experiences.

What is OpenClaw?

OpenClaw combines several core components:

• Personal Assistant: AI agent runtime managing conversations across multiple messaging channels
• Gateway Architecture: WebSocket-based control plane coordinating messaging, sessions, and routing
• Workspace System: File-based configuration and state management for agents and memory
• Memory System: Daily logs, long-term memory, and vector-based semantic search
• Skills System: Extensible knowledge layer that guides agent behavior
• Hooks System: Event-driven automation at lifecycle points
• Multi-Channel Support: WhatsApp, iMessage, Telegram, Discord, Signal, Slack, Matrix, and more
• Multi-Agent Support: Multiple independent agents with session routing and configuration

Installation & Setup

Quick start:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

For detailed installation instructions, platform-specific setup, macOS permissions (TCC), channel configuration (WhatsApp, iMessage, Telegram, etc.), gateway startup, health checks, and troubleshooting, see references/skill-installation-setup.md.

Core Architecture

OpenClaw uses a gateway-centric architecture where:

• Gateway (WebSocket server) coordinates all messaging and routing between channels and agents
• Agents (isolated AI brains) process messages with their own workspace, memory, tools, and sessions
• Sessions (conversation threads) maintain context per channel
• Channels (WhatsApp, iMessage, etc.) route messages to agents based on configuration rules

The agent loop processes messages through 6 phases: intake → context assembly → inference → tool execution → streaming → persistence.

For detailed architecture including agent loop phases, protocol specifications, model providers, queue management, and context handling, see references/skill-architecture.md.

Workspace System

Workspace contains configuration files that define agent behavior:

Core files:
- AGENTS.md - Operating instructions (rules, priorities, memory capture)
- SOUL.md - Persona and communication style
- USER.md - User information and preferences
- IDENTITY.md - Agent name, emoji, vibe
- TOOLS.md - Available tools and restrictions
- BOOT.md - Startup checklist
- BOOTSTRAP.md - First-run setup ritual
- HEARTBEAT.md - Regular maintenance tasks

Location: ~/.openclaw/workspace/

For complete markdown examples and templates of each workspace file, plus git backup patterns, see references/skill-workspace-configuration.md.

Memory System

• Daily logs (memory/YYYY-MM-DD.md) - Auto-created per day, captures events/decisions/insights
• Long-term memory (MEMORY.md) - Persistent accumulation of important context
• Vector search - Semantic memory search across history using embeddings
• Session memory - Optional transcript indexing (experimental)

Commands: openclaw memory status|search|flush|compact

For memory file examples, vector search configuration (OpenAI, Gemini, Anthropic providers), hybrid search, and automatic memory flush details, see references/skill-memory-system.md.

Skills System

Skills are markdown files with frontmatter that provide domain expertise:

• Loading: workspace skills → managed skills → bundled skills (precedence order)
• Triggering: Automatically loaded when conversation context matches skill description
• Gating: Control loading with metadata (requires, os, env, config)
• Per-agent: Each agent can enable/disable different skills

Commands: openclaw skills list|show|install|search|update

ClawHub registry for discovering and installing community skills.

Hooks System

Hooks are event-driven scripts triggered by lifecycle events:

• Events: SESSION_START, SESSION_END, MESSAGE_IN, MESSAGE_OUT, TOOL_CALL, TOOL_RESULT, COMMAND, GATEWAY_START, CHANNEL_CONNECT, ERROR
• Loading: workspace hooks → managed hooks → bundled hooks (precedence order)
• Bundled hooks: session-memory, command-logger, boot-md, soul-evil

Commands: openclaw hooks list|show|enable|disable

For detailed skill/hook structure, configuration, frontmatter examples, TypeScript implementation examples, and development workflows, see references/skill-skills-and-hooks.md.

System Prompts

System prompts define how the model behaves. OpenClaw constructs them dynamically with sections:

1. Role - Agent identity and purpose
2. Instructions - AGENTS.md content
3. Persona - SOUL.md content
4. Tooling - Available tools
5. Skills - Auto-injected loaded skills
6. Safety - Safety constraints
7. Memory - Memory instructions
8. Bootstrap - Current bootstrap state

Prompt modes: full (default), minimal (role+instructions+tools), none (experimental)

Customize via configuration: includeSkills, includeMemory, maxSkillsTokens, maxMemoryTokens

Common Workflows

Quick patterns:

• First run: curl install.sh | bash && openclaw onboard
• Multi-agent: openclaw agents create --name work && openclaw agents configure
• Memory backup: cd ~/.openclaw/workspace && git init && git push
• Skill install: openclaw skills search <topic> && openclaw skills install community/<skill>
• Hook dev: Create in ~/.openclaw/workspace/hooks/<name>/ with frontmatter + TypeScript

For detailed workflows including session start routines, memory capture patterns, skill installation, hook development, bootstrap rituals, and workspace backup automation, see references/skill-workflows.md.

Quick Reference Commands

Status & Health

openclaw status                # Overall system status
openclaw health --verbose      # Detailed health check
openclaw doctor                # Systematic diagnosis
openclaw gateway status         # Gateway running?
openclaw channels status        # Connected channels
openclaw sessions list          # Active sessions
openclaw memory status          # Memory system health
openclaw queue status           # Queue depth and stats

Gateway Control

openclaw gateway --port 18789                    # Start manually
openclaw gateway status                          # Check status
launchctl start ai.openclaw.gateway              # Start service
launchctl stop ai.openclaw.gateway               # Stop service
launchctl restart ai.openclaw.gateway            # Restart service

Channel Management

openclaw channels list                           # Show all channels
openclaw channels whatsapp:setup                 # Add WhatsApp
openclaw channels whatsapp:status                # Check WhatsApp
openclaw channels imessage:setup                 # Add iMessage
openclaw channels telegram:setup                 # Add Telegram
openclaw channels <channel>:disconnect           # Disconnect channel

Agent Management

openclaw agents list                             # Show all agents
openclaw agents create --name work               # Create new agent
openclaw agents config --agent=work              # Configure agent
openclaw agents reset                            # Reset all agents
openclaw agents show <agent-id>                  # Show agent details

Session Management

openclaw sessions list                           # Show active sessions
openclaw sessions show <session-id>              # View specific session
openclaw sessions reset                          # Clear all sessions
openclaw sessions reset --channel whatsapp       # Clear WhatsApp sessions

Memory Management

openclaw memory status                           # Memory system health
openclaw memory list                             # Show memory files
openclaw memory show 2025-02-01                  # View daily log
openclaw memory search "kubernetes"              # Search memory
openclaw memory flush                            # Manual flush
openclaw memory compact                          # Compaction
openclaw memory edit                             # Edit MEMORY.md

Skills Management

openclaw skills list                             # Show loaded skills
openclaw skills show <skill-name>                # View skill details
openclaw skills search machine-learning          # Search ClawHub
openclaw skills install community/<skill>        # Install skill
openclaw skills uninstall <skill>                # Remove skill
openclaw skills update                           # Update all skills

Hooks Management

openclaw hooks list                              # Show all hooks
openclaw hooks show <hook-name>                  # View hook details
openclaw hooks enable <hook-name>                # Enable hook
openclaw hooks disable <hook-name>               # Disable hook

Configuration

openclaw configure                               # Interactive config
openclaw configure --model gpt-4o                # Set model
openclaw configure --token $OPENAI_API_KEY       # Set API key
openclaw models list                             # Show models
openclaw models set --model gpt-4o               # Set active model

Reference Documentation

How to Find Documentation

The references/ directory contains two types of documentation:

1. Skill-generated guides (prefix: skill-*.md) - Condensed, practical guides extracted from this SKILL.md
2. Official documentation (no prefix) - Downloaded from https://docs.openclaw.ai/

Complete index: See references/SKILL-INDEX.md for all 241+ official documentation files with local links.

Source manifest: See references/llms.txt for the original URL list from docs.openclaw.ai.

Skill-Generated Guides (Condensed)

• skill-installation-setup.md - Complete setup walkthrough with all installation methods, macOS permissions, channel configuration
• skill-architecture.md - System architecture, gateway internals, agent loop, session management, protocol
• skill-workspace-configuration.md - All workspace file templates (AGENTS.md, SOUL.md, USER.md, etc.)
• skill-memory-system.md - Memory files, vector search configuration, hybrid search
• skill-skills-and-hooks.md - Skills/hooks development, structure, configuration
• skill-workflows.md - Common operational patterns and workflows

Official Documentation (From docs.openclaw.ai)

Quick Links to Common Topics:

Getting Started:
setup.md | getting-started.md | onboarding.md | wizard.md | macos.md

Configuration:
configuration.md | configuration-examples.md | environment.md | agent-workspace.md | system-prompt.md

Architecture:
architecture.md | gateway.md | agent.md | agent-loop.md | session.md | channel-routing.md | protocol.md | messages.md

Channels:
whatsapp.md | imessage.md | telegram.md | discord.md | signal.md | slack.md | googlechat.md | msteams.md | matrix.md

Memory & Skills:
memory.md | skills.md | skills-config.md | clawhub.md

Hooks & Advanced:
hooks.md | browser.md | browser-login.md | lobster.md | subagents.md | elevated.md | sandboxing.md

Troubleshooting:
troubleshooting.md | doctor.md | debugging.md

Deployment:
docker.md | linux.md | fly.md | railway.md | remote.md | tailscale.md

Tools:
exec.md | apply-patch.md | llm-task.md | agent-send.md | web.md | slash-commands.md

Additional Topics:
authentication.md | security.md | pairing.md | multi-agent.md | model-providers.md | formal-verification.md | token-use.md | testing.md

For questions about specific features, start with the skill-generated guides for condensed information, or consult the official documentation for comprehensive details.