openclaw-expert

OpenClaw Expert

Expert in the OpenClaw architecture, implementation, and ecosystem.

Core Competencies

1. Architecture

• Gateway hub-and-spoke model: Single Gateway coordinates all channels, sessions, clients, and nodes
• WebSocket + HTTP multiplexing: Single port (18789) handles control plane and API
• Session management: JSONL transcripts, reset policies, identity linking, compaction
• Agent execution: Streaming responses, tool orchestration, model failover, subagent spawning
• Device nodes: iOS/Android/macOS companions with camera, voice, screen, canvas
• Multi-agent routing: Multiple named agents with per-agent config and model selection

2. Messaging Integration

• 20+ platforms: WhatsApp (Baileys), Telegram (grammY), Discord, Slack, iMessage, Signal, Google Chat, Teams, Matrix, Line, BlueBubbles, Zalo, Nostr, Twitch, and more
• Channel adapters: Normalize platform messages to common format
• Session scoping: main, per-sender, per-channel-peer, per-account-channel-peer
• Identity linking: Map provider IDs to canonical identities
• Voice calls: Twilio/Telnyx/Plivo integration

3. Tool Ecosystem

• 30+ built-in tools: Filesystem, execution, web, browser, messaging, nodes, sessions, memory, automation
• Security model: Allowlist/denylist, tool groups, approval gates, sandboxing
• Browser automation: CDP + Playwright, AI snapshots with numeric refs
• Node capabilities: camera., canvas., screen.record, location.get, sms.send
• Subagent tools: sessions_spawn for parallel/background agent work

4. Memory & Knowledge

• Workspace files: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md
• Daily memory: memory/YYYY-MM-DD.md files
• QMD backend: Opt-in vector memory with SQLite + embeddings

5. Extension Mechanisms

• Skills: SKILL.md format with YAML frontmatter, three-tier loading
• Plugins: Node.js plugins with SDK, CLI/tools/handlers registration (32+ extensions)
• Channels: Custom platform adapters implementing Channel interface
• Hooks: Lifecycle hooks (pre/post/error) for gateway/session/agent/channel events

Key Concepts

Gateway: Always-on process owning connections, sessions, state, tool execution, event broadcasting.

Sessions: Conversation threads with unique IDs (DM, group, subagent, cron, webhook, node).

Agents: Isolated execution contexts — load history, build prompt, call LLM, stream response, execute tools.

Channels: Platform SDK wrapping, message normalization, presence handling.

Nodes: Device companions exposing camera, voice, screen, location, SMS capabilities.

Message Flow:

Platform SDK -> Channel Adapter -> Gateway Router -> Session Manager
  -> Agent Executor -> Tool Executor -> Session Manager -> Gateway Router
  -> Channel Adapter -> Platform SDK

When to Use

• Analyzing OpenClaw's Gateway architecture
• Tracing message flow from platform to agent to response
• Extending with skills, plugins, channels, or tools
• Debugging session lifecycle or tool execution issues
• Comparing hub-and-spoke vs other architectural patterns

Design Principles

1. Single-user by design (simplifies auth)
2. Gateway as authority (all state owned by Gateway)
3. Device-based trust (pairing per device)
4. Protocol-first (TypeBox schemas generate JSON Schema + Swift models)
5. Idempotent operations (side effects require idempotency keys)
6. Multi-agent safety (concurrent agents with session isolation)

CLI Reference

openclaw gateway [run] [--port 18789]    # Start gateway
openclaw agents list|add|delete           # Agent management
openclaw channels status [--probe]        # Channel status
openclaw memory search "topic"            # Memory search
openclaw skills list|install|enable       # Skill management
openclaw status [--all] [--deep]          # System status
openclaw dashboard                        # Web UI

Comparison with OpenCode

Dimension	OpenClaw	OpenCode
Architecture	Gateway hub	Client/server (Hono)
Focus	Multi-channel assistant	Code editing
Execution	Distributed (nodes)	Server-local
Messaging	20+ platforms	None
Memory	Workspace files + QMD vectors	None
Deployment	Daemon (systemd/launchd)	Interactive CLI/server

Key insight: OpenClaw optimizes for always-on personal assistant across devices/channels. OpenCode optimizes for focused coding workflow in terminal. Complementary, not competing.