第1章 Introduction to OpenClaw

What is OpenClaw?

OpenClaw is a personal AI assistant that runs on your own devices. Not someone else's servers. Not a cloud provider's data center. Your laptop, your workstation, your infrastructure. It answers you on the channels you already use—Telegram, Discord, Slack, Signal, iMessage, WhatsApp, and over a dozen more—while keeping your data local and under your control.

# Minimal Installation and First Run
npm install -g openclaw@latest  # [1]
openclaw --version              # [2]

The project began as a response to a fundamental problem: modern AI assistants are powerful, but they come with a hidden cost. Every conversation you have with them becomes training data. Every document you analyze becomes someone else's asset. OpenClaw flips this model completely. Released under the MIT License, version 2026.4.4 represents a mature production system with 5,582 TypeScript files powering a complete ecosystem—not just another framework, but a full assistant platform.

This is not merely a library or SDK. OpenClaw includes a Gateway server that acts as the control plane, CLI tools for terminal interaction, native mobile companion apps for iOS and Android, and a plugin ecosystem spanning 95+ bundled extensions. When you install OpenClaw, you're not just getting code—you're getting a complete personal AI infrastructure.

🤿 深入底层: The Gateway protocol is implemented as a typed WebSocket wire protocol with TypeBox schemas. Every request, response, and event frame is validated at runtime, ensuring type safety across all clients—CLI, mobile apps, and web UI communicate through this single, well-defined contract.

The Local-First Philosophy

The local-first approach isn't just about privacy—it's about control, latency, and reliability. When your AI assistant runs locally, several profound changes occur:

Privacy becomes architecture, not policy. Cloud services promise not to use your data, but promises can change. Terms of service update. Companies get acquired. Business models shift. With OpenClaw, your data never leaves your devices by default. The file-based storage system (no database required) means everything—conversations, session state, agent configurations—lives as readable JSON files on your filesystem. You can inspect it, back it up, delete it, or migrate it. It's yours.

Latency disappears as a concern. Every cloud AI request involves network hops—DNS lookups, TLS handwires, datacenter routing, model loading, response streaming. Even with optimal conditions, you're measuring round trips in hundreds of milliseconds. OpenClaw's local Gateway eliminates this entirely. The WebSocket connection to your local gateway is faster than most network stack optimizations.

Reliability becomes deterministic. Cloud services go down. API rate limits trigger. Network connections fail. Your local OpenClaw instance doesn't depend on anyone else's infrastructure. Once set up, it works as long as your devices work.

There are trade-offs, of course. Running locally means you're responsible for maintenance. You need to handle updates. You need to manage API keys for model providers (OpenClaw connects to models like GPT-4 and Claude, but doesn't host them). For some users, this responsibility is a burden. For others—particularly technical users, developers, and privacy-conscious individuals—it's exactly the point.

⚠️ 避坑指南: OpenClaw stores sessions and configuration in ~/.openclaw/ by default. This directory contains sensitive data including API keys and conversation history. On multi-user systems, ensure proper file permissions are set. OpenClaw applies secure defaults, but you should verify: chmod 700 ~/.openclaw/.

OpenClaw Versus Alternatives

The AI landscape is crowded with frameworks, tools, and platforms. Understanding where OpenClaw fits requires comparing it with the most common alternatives.

Dimension	OpenClaw	LangChain	AutoGPT	ChatGPT/Claude
Type	Complete system	Framework	Agent framework	Cloud service
Deployment	Local-first	Your choice	Your choice	Cloud-only
Channels	20+ messaging apps	None (code-level)	None (web UI)	Web/app only
Privacy	Local by default	Depends on you	Depends on you	Cloud processing
Extensibility	Plugin ecosystem	Python/JS libraries	Agent chains	Custom GPTs only
Data control	File-based, accessible	Depends on you	Depends on you	Locked in cloud
Offline capable	Partial (no external models)	Yes	Yes	No
Setup complexity	Medium (onboarding wizard)	High (code required)	High (code required)	Low (web signup)

Versus LangChain: LangChain is a framework for building LLM applications. It provides abstractions, chains, agents, and tools—but it's a library, not a product. You write code to use it. OpenClaw is a complete system with CLI tools, mobile apps, and a running Gateway server. LangChain excels when you're building custom applications; OpenClaw excels when you want a personal assistant that just works across the tools you already use.

Versus AutoGPT: AutoGPT focuses on autonomous agent chains—agents that spawn sub-agents to complete complex tasks automatically. It's experimental and research-oriented. OpenClaw focuses on multi-channel messaging integration and reliable, practical AI assistance. OpenClaw agents are powerful, but they're designed for interactive assistance rather than autonomous problem-solving.

Versus ChatGPT/Claude: This is the most direct comparison. ChatGPT and Claude are incredibly capable cloud assistants with polished interfaces. But they come with limitations: your data trains their models (or could), you're limited to their web/app interfaces, and you're at their mercy for feature changes and uptime. OpenClaw runs locally, supports 20+ channels simultaneously, and gives you full control over your data and models. The trade-off is setup complexity and responsibility for maintenance.

☕ 茶水间时间: The name "OpenClaw" and its mascot (a lobster) reference "claw" as in clawing back control of your AI interactions. The project's Discord community sometimes uses lobster emojis, and you'll see crustacean-themed messaging throughout. It's a playful reminder that the project takes privacy and control seriously without taking itself too seriously.

Project Maturity and Ecosystem

OpenClaw is not an experimental prototype or research project. It's production software with active development, comprehensive testing, and real-world deployment.

CI/CD infrastructure runs on every commit, with type checking, linting, and automated tests across the codebase. The project maintains strict architecture boundaries—extensions must cross into core only through documented public SDK contracts, ensuring stability as the ecosystem grows.

The plugin ecosystem spans 95+ bundled plugins across multiple categories:

• Channel plugins connect to messaging platforms (Discord, Telegram, Matrix, Signal, iMessage, and 15+ more)
• Provider plugins integrate with AI model providers (OpenAI, Anthropic, Google, xAI, Moonshot, and others)
• Memory plugins add persistent storage (LanceDB, SQLite-based vector storage, file-based memory)
• Skill plugins extend agent capabilities with specialized tools and workflows

Native mobile apps provide companion experiences on iOS and Android. These aren't web wrappers—they're native Swift and Kotlin applications that connect to your local Gateway, putting AI assistance in your pocket with full privacy preservation.

Testing infrastructure covers 3,500 test files across unit, integration, and E2E suites. The project maintains 70% code coverage thresholds on critical paths, with Docker-based E2E tests validating real-world workflows including live model API calls.

The combination of mature tooling, active development, and comprehensive documentation makes OpenClaw viable for both personal use and production deployment. Whether you're a developer wanting to extend the system, a privacy-conscious user wanting local AI, or an organization needing internal AI infrastructure, OpenClaw provides a foundation rather than a starting point.

Chapter Exercises

1. Install OpenClaw locally using npm
   Run npm install -g openclaw@latest and verify the installation with openclaw --version. Then run openclaw onboard to start the setup wizard.

2. Compare OpenClaw vs ChatGPT feature matrix
   Create a table comparing five features: deployment location, data ownership, messaging channels, extensibility, and offline capability.

3. Identify three use cases where local-first matters
   Consider scenarios like healthcare, legal work, journalism, or corporate strategy. Why would local deployment be essential in each case?

Now that you understand what OpenClaw is and why it exists, let's explore how its components fit together in the overall architecture.