VibeAIHub

Openclaw · EN · Part 1

Ch 03 Quick Start And Installation

03-ch-03-Quick-Start-and-Installation.md

第3章 Quick Start and Installation

Installation Methods

OpenClaw offers three installation paths, each suited to different scenarios. The right choice depends on your environment, goals, and comfort level with development tools.

Rendering diagram...

Global npm install

The fastest path for most users. npm handles dependencies, binaries, and path configuration automatically.

npm install -g openclaw@latest

This single command:

  • Downloads the latest OpenClaw package from npm
  • Installs the openclaw binary globally
  • Sets up platform-specific dependencies (like sharp for image processing)
  • Creates symlinks so openclaw works from any directory

🤿 深入底层：OpenClaw's CLI entry point lives in openclaw.mjs, a Node.js wrapper that checks your Node version (requires 22.14+), enables compile cache for faster subsequent runs, and loads the actual TypeScript code from dist/entry.js. The version check happens before any code execution—if you're on Node 20 or earlier, you'll get a clear error message rather than a cryptic runtime failure.

Alternative package managers:

# pnpm (requires approving builds)
pnpm add -g openclaw@latest
pnpm approve-builds -g

# Bun (CLI-only usage)
bun install -g openclaw@latest

Troubleshooting: If sharp (image processing library) fails during installation due to a globally installed libvips:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

This tells sharp to ignore your system's libvips and use its bundled version instead.

Docker deployment

For containerized environments, headless servers, or when you want isolation from your host system.

FROM node:24-bookworm-slim
RUN npm install -g openclaw@latest
WORKDIR /data
CMD ["openclaw", "gateway", "run", "--bind", "0.0.0.0", "--port", "18789"]

Or use docker-compose for a complete stack:

# docker-compose.yml
services:
  openclaw:
    image: node:24-bookworm-slim
    command: openclaw gateway run --bind 0.0.0.0 --port 18789
    volumes:
      - ./openclaw-data:/root/.openclaw
    ports:
      - "18789:18789"
    restart: unless-stopped

Docker gives you:

  • Isolation: Dependencies stay in the container
  • Reproducibility: Same environment everywhere
  • Easy cleanup: Remove the container to reset

⚠️ 避坑指南：Docker volumes are crucial for persistence. The ~/.openclaw directory contains your configuration, sessions, and agent state. Mount it as a volume or your entire setup disappears when the container is removed.

Building from source

For contributors, or when you need the absolute latest commits from main:

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

# Install dependencies (requires pnpm)
pnpm install

# Build the UI and CLI
pnpm ui:build
pnpm build

# Link globally for `openclaw` command availability
pnpm link --global

# Or skip linking and use pnpm to run
pnpm openclaw --version

Building from source gives you:

  • Latest features: Commits from main before they reach npm
  • Development workflow: Edit code, rebuild, test immediately
  • Full control: Debug with source maps, run tests in place

The tradeoff? Longer setup time and you'll need to rebuild after pulling changes. For most users, npm install is sufficient.

Version checking

Regardless of installation method, verify your setup:

openclaw --version
# Output: OpenClaw 2026.4.4 (abc123def)  # [1]

The version number shows the release version, and the commit hash (in parentheses) indicates exactly which source code built this binary. This is invaluable when debugging—if something breaks, you can pinpoint the exact commit.

Why version checking matters: OpenClaw moves fast. A bug you encounter might already be fixed in main, or a feature you read about in documentation might require a newer version. Always check version first when something doesn't behave as expected.

First-Time Configuration

With OpenClaw installed, you need to configure it before it can think. The openclaw onboard command walks you through everything.

openclaw onboard --install-daemon

The --install-daemon flag (macOS/Linux) sets up the Gateway server to start automatically on boot. Skip it if you prefer manual control.

# Output example
? Choose what to set up:
  ❯ Full setup (recommended)
    Gateway only
    Channels only
    Model provider only

Select "Full setup" for your first run. Onboarding will:

  1. Start the Gateway server (the control plane we discussed in Chapter 2)
  2. Configure a model provider (OpenAI, Anthropic, Google, etc.)
  3. Set up messaging channels (Telegram, Discord, etc.)
  4. Install basic skills (optional)

Configuring model providers

OpenClaw doesn't include AI models itself—it connects to providers you configure. Onboarding prompts for your choice:

? Select a model provider:
  ❯ OpenAI (GPT-4, GPT-4o)
    Anthropic (Claude Sonnet, Claude Opus)
    Google (Gemini Pro, Gemini Ultra)
    xAI (Grok)
    Moonshot (Chinese-language models)

After selecting, provide your credentials:

? OpenAI API key: ************************************************************
? Use this key for all OpenAI models? Yes
? Set as default provider? Yes

Your API key goes directly to ~/.openclaw/credentials/—never in configuration files or environment variables that might be logged or shared.

☕ 茶水间时间：Why separate credentials from config? Config files often end up in version control, screenshots, or chat logs. Credentials should live in a dedicated, permissions-protected directory. OpenClaw's credentials/ folder is gitignored by default and never logged. If you accidentally commit config.json, your API keys remain safe.

Setting up basic channels

Next, onboarding asks which messaging channels to enable:

? Select channels to configure:
  ❯ Telegram
  ◯ Discord
  ◯ Slack
  ◯ Signal
  ◯ iMessage (macOS only)
  ◯ WhatsApp Web

Each channel has its own setup flow. For Telegram, you'll provide a bot token:

? Telegram bot token: ************************************************************
? Enable inline queries? Yes
? Test the connection? Yes

Onboarding verifies the connection immediately. If your token is invalid or the bot can't reach Telegram's servers, you'll know before exiting the wizard.

Config system and doctor command

OpenClaw stores configuration in ~/.openclaw/config.json:

{
  "gateway": {
    "mode": "local",
    "host": "127.0.0.1",
    "port": 18789
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true,
        "accounts": {
          "default": {
            "token": "${TELEGRAM_BOT_TOKEN}"
          }
        }
      }
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    },
    "default": "openai:gpt-4o"
  }
}

Note the ${VARIABLE} syntax—these are SecretRefs that resolve from environment variables or the credentials store. The actual secrets never touch config.json.

When things don't work, run the diagnostic command:

openclaw doctor

This checks:

  • Node version compatibility
  • Gateway connection status
  • Plugin manifest validity
  • Channel configuration errors
  • Model provider credentials
  • File system permissions

Output looks like:

✓ Node 24.0.0 meets minimum requirement (22.14+)
✓ Gateway running at ws://127.0.0.1:18789
✓ Telegram plugin enabled and configured
✓ OpenAI provider configured
⚠ Default model not set (use 'openclaw config set models.default openai:gpt-4o')
✗ Signal plugin enabled but libsignal not found

Fix what's broken, rerun doctor, and proceed when you see all checks.

Sending Your First Message

With OpenClaw installed and configured, let's talk to it.

Running openclaw agent

The simplest way is through the CLI:

openclaw agent "What is the capital of France?"

This command:

  1. Connects to the Gateway server via WebSocket
  2. Creates a session (or reuses an existing one)
  3. Sends your message to the configured AI model
  4. Streams the response back to your terminal

Gateway connection observation

Behind the scenes, here's what happens:

Rendering diagram...

The Gateway protocol (RequestFrame/ResponseFrame/EventFrame from Chapter 2) handles every interaction. You don't see these frames—they're internal—but understanding they exist explains why the CLI can disconnect and reconnect without losing state.

Agent response

Back in your terminal:

[openclaw] Connecting to Gateway at ws://127.0.0.1:18789...
[openclaw] Session: main (active)
[Runtime] Using model: openai:gpt-4o

The capital of France is Paris. It's been the country's capital city since
508 AD and is known for landmarks like the Eiffel Tower, the Louvre Museum,
and Notre-Dame Cathedral.

[Session: main] Tokens: 42 in, 38 out | Cost: $0.0002

The response includes:

  • Connection status: Confirms Gateway connectivity
  • Session info: Which session handled this (we'll cover sessions in Chapter 14)
  • Model used: Which provider/model answered
  • Token/cost tracking: Usage metrics for cost awareness

Session model and CLI options

By default, openclaw agent uses the main session—a persistent context that remembers conversation history. Ask a follow-up question:

openclaw agent "And what's its population?"

The agent knows "its" refers to Paris, because session context includes previous messages.

CLI options for common tasks:

# Start an interactive session (chat mode)
openclaw agent --interactive

# Use a specific model (override default)
openclaw agent "Explain quantum physics" --model openai:o1-preview

# Specify thinking mode (controls chain-of-thought depth)
openclaw agent "Debug this code" --thinking high

# Stream without waiting for completion
openclaw agent "Summarize this file" --message "$(cat file.md)"

# Clear session history
openclaw sessions reset main

🤿 深入底层：Sessions are stored as JSONL files in ~/.openclaw/agents/<agent-id>/sessions/*.jsonl. Each line is a JSON object representing a message, response, or event. This file-based approach (no database) keeps OpenClaw portable and inspectable—you can cat a session file to see exactly what was said, when, and with what metadata.

Essential CLI Commands

You've installed, configured, and sent your first message. Now let's survey the CLI commands you'll use regularly.

openclaw agent

We've covered the basics, but agent has more power:

# Interactive mode (stay in the conversation)
openclaw agent --interactive
> What is OpenClaw?
[agent responds]
> How does it work?
[agent responds, remembering context]
> Ctrl+D to exit

# Non-interactive (single message, then exit)
openclaw agent "Hello, world"

# Reply to a specific message (for threading)
openclaw agent "My response" --in-reply-to <message-id>

# Use a specific agent identity
openclaw agent "Draw me a picture" --agent canvas-agent

openclaw gateway

The Gateway server commands manage the control plane:

# Start the Gateway manually (if not using daemon)
openclaw gateway run

# Check Gateway status
openclaw gateway status

# Restart the Gateway (useful after config changes)
openclaw gateway restart

# Stop the Gateway
openclaw gateway stop

# View Gateway logs
openclaw gateway logs --follow

Gateway modes:

  • local (default): Runs on your machine, accessible only from localhost
  • network (advanced): Binds to all interfaces for remote access (requires auth)
  • Development mode: --dev flag enables hot-reload and verbose logging

openclaw channels

Channel management commands:

# List all configured channels
openclaw channels list

# Show detailed status for a channel
openclaw channels status --channel telegram

# Add a new channel account
openclaw channels add telegram --token <bot-token>

# Remove a channel
openclaw channels remove telegram --account default

# Probe all channels (test connectivity)
openclaw channels status --probe

Status output example:

Channel     Account     Status       Last Message
─────────── ─────────── ───────────── ────────────────────────
Telegram    default     ✅ Connected  2 minutes ago
Discord     bot         ✅ Connected  15 minutes ago
WhatsApp    web         ⚠️ Idle      2 hours ago

openclaw config and doctor

Configuration management and diagnostics:

# Get a config value
openclaw config get models.default

# Set a config value
openclaw config set models.default anthropic:claude-sonnet-4.6

# List all config keys
openclaw config list

# Validate configuration without changing it
openclaw doctor --dry-run

# Fix common issues automatically
openclaw doctor --fix

Config scopes:

  • models.*: Model providers and default selection
  • gateway.*: Gateway server settings
  • plugins.entries.<plugin>.*: Per-plugin configuration
  • sessions.*: Session behavior and defaults
# Example: Set Gateway to bind all interfaces
openclaw config set gateway.host 0.0.0.0
openclaw gateway restart  # Required for changes to take effect

You've installed OpenClaw, configured it with a model provider and channels, and sent your first message. The CLI is your control surface—whether running interactively or scripting with single commands. Sessions maintain context across conversations, and the Gateway protocol handles everything behind the scenes.

But what exactly is happening when that WebSocket connects? How do the Gateway, your CLI, and messaging channels coordinate to deliver responses? We've seen the protocol frames from Chapter 2—now let's dive into the Gateway server that makes all communication possible.

Chapter Exercises

  1. Install and verify: Install OpenClaw using your preferred method (npm, Docker, or source). Run openclaw --version and openclaw doctor to confirm everything works.

  2. Complete onboarding: Run openclaw onboard --install-daemon and configure at least one model provider and one messaging channel. Verify the channel with openclaw channels status --probe.

  3. Send and trace: Send a message via openclaw agent, then find and inspect the resulting session file in ~/.openclaw/agents/<agent-id>/sessions/. Identify the JSON structure for your message and the agent's response.