OpenClaw Documentation: Complete Reference Guide (2026)

# Install OpenClaw
curl -fsSL https://get.openclaw.com | bash

# Create an agent workspace with SOUL.md
mkdir -p agents/my-agent && cat > agents/my-agent/SOUL.md << 'EOF'
# My First Agent

## Identity
- Name: Assistant
- Role: General-purpose AI assistant

## Personality
- Helpful and concise
- Responds in clear, actionable language

## Rules
- Always provide sources when citing facts
- Keep responses under 500 words unless asked for more
EOF

# Register agent and start gateway
openclaw agents add my-agent --workspace ./agents/my-agent
openclaw gateway start

# Agent Display Name

## Identity
- Name: Agent Name
- Role: What this agent does
- Model: claude-sonnet-4-20250514
- Provider: anthropic

## Personality
- Describe the agent's communication style
- Tone, formality, and approach to tasks
- How the agent interacts with users

## Rules
- Specific instructions the agent must follow
- Constraints on behavior and output
- Formatting requirements
- Domain-specific guidelines

## Skills
- browser: Search the web and browse pages
- scraper: Extract content from URLs
- file_manager: Read and write local files
- code_runner: Execute code snippets

## Channels
- telegram: @YourBotUsername
- slack: #channel-name
- discord: server-id/channel-id
- email: agent@yourdomain.com

## Knowledge
- Reference documents the agent should know about
- Links to internal wikis or documentation
- Domain-specific context files

# Content Production Team

## Agents
- @researcher: Finds data, statistics, and source material
- @writer: Creates blog posts and articles from research
- @editor: Reviews drafts for quality and accuracy
- @publisher: Formats and publishes final content

## Workflow
1. @researcher gathers information on the assigned topic
2. @researcher hands findings to @writer
3. @writer drafts the article using the research
4. @writer sends the draft to @editor
5. @editor reviews, provides feedback, and approves
6. @editor passes approved content to @publisher
7. @publisher formats and delivers the final version

## Handoff Rules
- @researcher always passes to @writer, never directly to @editor
- @editor can send content back to @writer for revisions
- @publisher is the final step and does not hand off to other agents
- All agents respond in English only

# Available Tools

## Analytics
- `node scripts/analytics/ga4-traffic.cjs` — Fetch GA4 traffic data
- `node scripts/analytics/mixpanel-funnel.cjs` — Get funnel metrics
- `node scripts/analytics/stripe-report.cjs` — Stripe revenue report

## Content
- `node scripts/content/publish.cjs` — Publish content to CMS
- `node scripts/content/screenshot.cjs [url]` — Capture page screenshot

## Notifications
- `node scripts/notify/telegram.cjs [message]` — Send Telegram alert
- `node scripts/notify/slack.cjs [channel] [message]` — Post to Slack

# Heartbeat Schedule

## Every Morning at 9:00 AM
- Check analytics dashboard for anomalies
- Generate daily traffic report
- Send summary to Telegram

## Every Monday at 10:00 AM
- Compile weekly performance report
- Compare metrics to previous week
- Flag any metrics that dropped more than 20%

## Every 6 Hours
- Monitor uptime for all tracked services
- Alert immediately if any service is down

## First Day of Month
- Generate monthly revenue report
- Calculate MoM growth rates
- Send full report to email channel

# Agent Memory

## Project Context
- Product: SaaS analytics dashboard
- Stack: Next.js, TypeScript, PostgreSQL
- Launch date: March 2026
- Current phase: Beta testing

## Key Decisions
- Chose Stripe over Paddle for payments (Jan 15)
- Migrated from REST to GraphQL API (Jan 22)
- Switched from Vercel to self-hosted (Feb 1)

## User Preferences
- Prefers concise responses with bullet points
- Wants code examples in TypeScript
- Reports should include week-over-week comparison
- Never include emojis in reports

# User Profile

## Communication
- Language: English
- Timezone: UTC+3
- Availability: Weekdays 9 AM - 6 PM
- Preferred channel: Telegram

## Expertise Level
- Technical background: Senior developer
- Familiar with: Python, TypeScript, Docker, AWS
- New to: Machine learning, Kubernetes

## Notification Preferences
- Critical alerts: Immediate via Telegram
- Daily reports: 9 AM via Email
- Weekly summaries: Monday 10 AM via Slack

# Add a new agent from a workspace directory
openclaw agents add <name> --workspace <path>

# List all registered agents
openclaw agents list

# Remove a registered agent
openclaw agents remove <name>

# Send a message to a specific agent
openclaw agent --agent <name> --message "Your message here"

# Show agent details and configuration
openclaw agents info <name>

# Start the gateway (background daemon)
openclaw gateway start

# Stop the running gateway
openclaw gateway stop

# Restart the gateway (stop + start)
openclaw gateway restart

# Run gateway in foreground (useful for debugging)
openclaw gateway run

# Check gateway status
openclaw gateway status

# Get a configuration value
openclaw config get <key>

# Set a configuration value
openclaw config set <key> <value>

# List all configuration values
openclaw config list

# Examples
openclaw config set gateway.port 18789
openclaw config set provider anthropic
openclaw config set model claude-sonnet-4-20250514
openclaw config get gateway.port

# List all configured channels
openclaw channels list

# Show channel connection status
openclaw channels status

# Connect a channel to an agent
openclaw channels connect <channel-type> --agent <name>

# Disconnect a channel
openclaw channels disconnect <channel-type> --agent <name>

# Check OpenClaw version
openclaw version

# Update to latest version
openclaw update

# View logs
openclaw logs

# Clear agent session data
openclaw sessions clear --agent <name>

# Health check
openclaw doctor

# Change the gateway port
openclaw config set gateway.port 8080

# Allow network access (not just localhost)
openclaw config set gateway.bind 0.0.0.0

# Enable authentication
openclaw config set gateway.auth enabled
openclaw config set gateway.auth_token your-secret-token-here

# Enable Tailscale integration for remote access
openclaw config set gateway.tailscale enabled

# Increase concurrent request limit
openclaw config set gateway.max_concurrent 10

# Apply changes
openclaw gateway restart

# Global configuration
openclaw config set provider anthropic
openclaw config set anthropic.api_key sk-ant-your-key-here

# Available models
# claude-sonnet-4-20250514 (recommended for most agents)
# claude-opus-4-20250514 (highest capability)
# claude-haiku-235 (fastest, lowest cost)

# Per-agent in SOUL.md
## Identity
- Model: claude-sonnet-4-20250514
- Provider: anthropic

# Global configuration
openclaw config set provider openai
openclaw config set openai.api_key sk-your-key-here

# Available models
# gpt-4o (recommended)
# gpt-4o-mini (lower cost)
# o1 (advanced reasoning)

# Per-agent in SOUL.md
## Identity
- Model: gpt-4o
- Provider: openai

# Global configuration
openclaw config set provider google
openclaw config set google.api_key your-google-api-key

# Available models
# gemini-2.5-pro (recommended)
# gemini-2.5-flash (faster, lower cost)

# Per-agent in SOUL.md
## Identity
- Model: gemini-2.5-pro
- Provider: google

# Install Ollama first (https://ollama.com)
# Pull a model
ollama pull llama3.1
ollama pull mistral
ollama pull codellama

# Global configuration
openclaw config set provider ollama
openclaw config set ollama.host http://localhost:11434

# Available models (depends on what you have pulled)
# llama3.1 (general purpose, recommended)
# mistral (fast, good for simple agents)
# codellama (code-focused tasks)
# deepseek-coder (coding agents)

# Per-agent in SOUL.md
## Identity
- Model: llama3.1
- Provider: ollama

# 1. Create a service account in Google Cloud Console
# 2. Download the JSON key file
# 3. Add the service account email as a Viewer in GA4 Admin

# Configure in OpenClaw
openclaw config set integrations.ga4.property_id "123456789"
openclaw config set integrations.ga4.credentials_path "./credentials/ga4-key.json"

# Reference in TOOLS.md for agent access
# `node scripts/analytics/ga4-traffic.cjs` — Fetch GA4 traffic data

# 1. Get your project token and API secret from Mixpanel Settings
# 2. Configure in OpenClaw

openclaw config set integrations.mixpanel.token "your-project-token"
openclaw config set integrations.mixpanel.api_secret "your-api-secret"

# Agents can query Mixpanel for funnel data, event counts,
# and user analytics through TOOLS.md scripts

# 1. Get your Stripe API key from the Stripe Dashboard
# 2. Use a restricted key with read-only access for safety

openclaw config set integrations.stripe.api_key "sk_live_your-key"

# Agents can fetch revenue reports, subscription counts,
# cancellation data, and payment events

# 1. Create a personal access token (PAT) with repo scope
# 2. Configure in OpenClaw

openclaw config set integrations.github.token "ghp_your-token"
openclaw config set integrations.github.default_repo "username/repo"

# Agents can create issues, read PRs, check CI status,
# and interact with your repositories

# 1. Create an integration at https://www.notion.so/my-integrations
# 2. Share your Notion pages/databases with the integration
# 3. Configure in OpenClaw

openclaw config set integrations.notion.token "ntn_your-token"
openclaw config set integrations.notion.workspace_id "your-workspace-id"

# Agents can read pages, update databases, create entries,
# and search across your Notion workspace

# Configure database connection
openclaw config set integrations.postgres.host "localhost"
openclaw config set integrations.postgres.port 5432
openclaw config set integrations.postgres.database "your_database"
openclaw config set integrations.postgres.user "your_user"
openclaw config set integrations.postgres.password "your_password"

# Use read-only credentials for safety
# Agents can query data, generate reports, and monitor metrics
# Configure allowed tables in TOOLS.md to prevent unintended access

# Install OpenClaw
curl -fsSL https://get.openclaw.com | bash

# Configure your agents
openclaw agents add my-agent --workspace ./agents/my-agent

# Start gateway (registers with launchd automatically)
openclaw gateway start

# To manage with launchd directly
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Prevent sleep when on AC power (for always-on agents)
sudo pmset -c sleep 0

# Install OpenClaw
curl -fsSL https://get.openclaw.com | bash

# Configure agents
openclaw agents add my-agent --workspace ./agents/my-agent

# Create systemd service
cat > ~/.config/systemd/user/openclaw-gateway.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway run
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

# Check status
systemctl --user status openclaw-gateway

# Install on Raspberry Pi (ARM64)
curl -fsSL https://get.openclaw.com | bash

# Install Ollama for local model inference
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1:8b  # Use smaller models for Pi

# Configure for local-only operation
openclaw config set provider ollama
openclaw config set ollama.host http://localhost:11434

# Use systemd for auto-start (same as Linux)
# Enable Tailscale for remote access from anywhere
openclaw config set gateway.tailscale enabled

# Using the official Docker image
docker pull openclaw/gateway:latest

# Run with mounted agent workspace
docker run -d \
  --name openclaw-gateway \
  -p 18789:18789 \
  -v $(pwd)/agents:/app/agents \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  openclaw/gateway:latest

# Docker Compose for multi-service setup
# docker-compose.yml
version: "3.8"
services:
  gateway:
    image: openclaw/gateway:latest
    ports:
      - "18789:18789"
    volumes:
      - ./agents:/app/agents
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    restart: unless-stopped

# On your VPS (Ubuntu)
curl -fsSL https://get.openclaw.com | bash

# Configure agents
openclaw agents add my-agent --workspace ./agents/my-agent
openclaw config set gateway.bind 127.0.0.1

# Set up nginx as reverse proxy
sudo apt install nginx certbot python3-certbot-nginx

# /etc/nginx/sites-available/openclaw
server {
    server_name agents.yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

# Enable HTTPS
sudo certbot --nginx -d agents.yourdomain.com

# Start everything
openclaw gateway start
sudo systemctl restart nginx