Openclaw Chinese Documentation

OpenClaw Chinese Documentation Skill

Skill by ara.so — Hermes Skills collection.

Expert knowledge for installing, configuring, and deploying OpenClaw, a self-hosted multi-channel AI assistant platform. This skill covers the comprehensive Chinese documentation repository (yeuxuan/openclaw-docs) which provides 767 tutorials across installation, architecture, AI framework, and channel adapters.

What is OpenClaw?

OpenClaw is an open-source personal AI assistant platform that runs on your own infrastructure. It uses a Gateway architecture to unify:

• Web Control UI for management
• Chat Channels (WhatsApp, Telegram, Discord, Slack, Feishu, etc.)
• Nodes (mobile/remote execution endpoints)
• Tools (browser, code execution, sub-agents)
• AI Models (Claude, GPT, DeepSeek, Qwen, Ollama, etc.)

Documentation Structure

The openclaw-docs repository contains 767 articles organized into 4 learning tracks:

Track 0: Installation Tutorials (680 articles)

• Quick start and guided installation
• Docker / Node.js / cloud server deployment
• Gateway configuration and operations
• Channel integration (Telegram, WhatsApp, Discord, etc.)
• AI provider setup (Anthropic, OpenAI, DeepSeek, Ollama, etc.)
• Core concepts (context, memory, state machine)
• Tools system (browser, execution, skills, sub-agents)
• Plugin development (Manifest, SDK, Hooks)
• Platform support (macOS, Windows, Linux, mobile, VPS)
• Troubleshooting and diagnostics

Track A: Complete Engineering Path (62 articles)

• CLI startup framework
• Gateway control plane
• Plugin and channel adapter architecture
• Node system
• Routing and session keys
• Agent execution pipeline
• Function-level source code analysis

Track B: AI Core Framework (24 articles)

• Context engineering
• Agent state machine
• Tool strategy and approval
• Model fallback
• Memory system
• Hook plugin injection mechanism

Track C: Channel Adapters

• Interface contracts
• Registration pipeline
• Account lifecycle
• Inbound routing
• Outbound sending decoupling

Running the Documentation Locally

# Clone the documentation repository
git clone https://github.com/yeuxuan/openclaw-docs.git
cd openclaw-docs

# Install dependencies
npm install

# Run development server
npm run docs:dev

# Build static site
npm run docs:build

# Preview built site
npm run docs:preview

The documentation is built with VitePress and deployed on Azure Static Web Apps at openclaw-docs.dx3n.cn.

Quick Start: Installing OpenClaw

Prerequisites

# Node.js 18+ required
node --version

# Docker (optional, for containerized deployment)
docker --version

Basic Installation

# Install OpenClaw globally via npm
npm install -g openclaw

# Or use npx for one-time execution
npx openclaw init

# Initialize a new OpenClaw instance
openclaw init my-assistant
cd my-assistant

# Start the gateway
openclaw start

Docker Installation

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  openclaw-gateway:
    image: openclaw/gateway:latest
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - GATEWAY_PORT=3000
      - DATABASE_URL=${DATABASE_URL}
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    restart: unless-stopped
EOF

# Start with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f openclaw-gateway

Configuration

Gateway Configuration (config/gateway.yml)

gateway:
  port: 3000
  host: 0.0.0.0
  baseUrl: https://your-domain.com

database:
  type: sqlite
  path: ./data/openclaw.db

ai:
  defaultProvider: anthropic
  providers:
    anthropic:
      apiKey: ${ANTHROPIC_API_KEY}
      model: claude-3-5-sonnet-20241022
    
    openai:
      apiKey: ${OPENAI_API_KEY}
      model: gpt-4
    
    ollama:
      baseUrl: http://localhost:11434
      model: llama2

memory:
  enabled: true
  maxTokens: 100000
  provider: sqlite

tools:
  browser:
    enabled: true
    headless: true
  
  codeExecution:
    enabled: true
    sandboxed: true

Environment Variables (.env)

# AI Provider Keys
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
DEEPSEEK_API_KEY=your_key_here

# Database
DATABASE_URL=sqlite:./data/openclaw.db

# Gateway
GATEWAY_SECRET=your_secret_here
NODE_ENV=production

# Channel Tokens
TELEGRAM_BOT_TOKEN=your_token_here
DISCORD_BOT_TOKEN=your_token_here
WHATSAPP_API_KEY=your_key_here
FEISHU_APP_ID=your_app_id_here
FEISHU_APP_SECRET=your_app_secret_here

Channel Integration

Telegram Setup

// config/channels/telegram.js
export default {
  type: 'telegram',
  enabled: true,
  config: {
    token: process.env.TELEGRAM_BOT_TOKEN,
    polling: true,
    commands: {
      start: 'Welcome to OpenClaw!',
      help: 'I can help you with various tasks.'
    }
  },
  routing: {
    sessionKey: 'telegram:{chatId}',
    defaultAgent: 'main'
  }
};

WhatsApp Setup (via WhatsApp Business API)

// config/channels/whatsapp.js
export default {
  type: 'whatsapp',
  enabled: true,
  config: {
    apiKey: process.env.WHATSAPP_API_KEY,
    webhookUrl: '/webhook/whatsapp',
    phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
    verifyToken: process.env.WHATSAPP_VERIFY_TOKEN
  },
  routing: {
    sessionKey: 'whatsapp:{phoneNumber}',
    defaultAgent: 'main'
  }
};

Discord Setup

// config/channels/discord.js
export default {
  type: 'discord',
  enabled: true,
  config: {
    token: process.env.DISCORD_BOT_TOKEN,
    intents: ['GUILDS', 'GUILD_MESSAGES', 'DIRECT_MESSAGES'],
    commandPrefix: '!'
  },
  routing: {
    sessionKey: 'discord:{userId}',
    defaultAgent: 'main'
  }
};

Feishu (Lark) Setup

// config/channels/feishu.js
export default {
  type: 'feishu',
  enabled: true,
  config: {
    appId: process.env.FEISHU_APP_ID,
    appSecret: process.env.FEISHU_APP_SECRET,
    verificationToken: process.env.FEISHU_VERIFICATION_TOKEN,
    encryptKey: process.env.FEISHU_ENCRYPT_KEY
  },
  routing: {
    sessionKey: 'feishu:{openId}',
    defaultAgent: 'main'
  }
};

AI Provider Configuration

Using Multiple Providers with Fallback

// config/ai.js
export default {
  providers: [
    {
      name: 'primary',
      type: 'anthropic',
      apiKey: process.env.ANTHROPIC_API_KEY,
      model: 'claude-3-5-sonnet-20241022',
      priority: 1
    },
    {
      name: 'fallback',
      type: 'openai',
      apiKey: process.env.OPENAI_API_KEY,
      model: 'gpt-4',
      priority: 2
    },
    {
      name: 'local',
      type: 'ollama',
      baseUrl: 'http://localhost:11434',
      model: 'llama2',
      priority: 3
    }
  ],
  
  fallbackStrategy: 'cascade',
  retryAttempts: 3,
  timeout: 30000
};

Chinese AI Providers

// config/providers/chinese.js
export default {
  deepseek: {
    apiKey: process.env.DEEPSEEK_API_KEY,
    baseUrl: 'https://api.deepseek.com',
    model: 'deepseek-chat'
  },
  
  qwen: {
    apiKey: process.env.QWEN_API_KEY,
    baseUrl: 'https://dashscope.aliyuncs.com/api/v1',
    model: 'qwen-max'
  },
  
  kimi: {
    apiKey: process.env.KIMI_API_KEY,
    baseUrl: 'https://api.moonshot.cn/v1',
    model: 'moonshot-v1-8k'
  },
  
  glm: {
    apiKey: process.env.GLM_API_KEY,
    baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
    model: 'glm-4'
  }
};

Plugin Development

Basic Plugin Structure

// plugins/my-plugin/manifest.json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Custom OpenClaw plugin",
  "author": "Your Name",
  "hooks": {
    "onMessage": "./hooks/onMessage.js",
    "beforeResponse": "./hooks/beforeResponse.js"
  },
  "tools": [
    {
      "name": "customTool",
      "description": "A custom tool",
      "handler": "./tools/customTool.js"
    }
  ]
}

Hook Implementation

// plugins/my-plugin/hooks/onMessage.js
export default async function onMessage(context, next) {
  const { message, session, agent } = context;
  
  // Pre-process message
  console.log(`Received message: ${message.text}`);
  
  // Add custom data to context
  context.customData = {
    timestamp: Date.now(),
    channelType: message.channel
  };
  
  // Continue to next middleware
  await next();
  
  // Post-process after agent response
  console.log(`Response sent to ${session.id}`);
}

Custom Tool Implementation

// plugins/my-plugin/tools/customTool.js
export default {
  name: 'customTool',
  description: 'Performs a custom action',
  
  parameters: {
    type: 'object',
    properties: {
      action: {
        type: 'string',
        description: 'The action to perform'
      },
      data: {
        type: 'object',
        description: 'Data for the action'
      }
    },
    required: ['action']
  },
  
  async execute({ action, data }, context) {
    // Tool implementation
    switch (action) {
      case 'query':
        return await performQuery(data);
      
      case 'update':
        return await performUpdate(data);
      
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }
};

async function performQuery(data) {
  // Implementation
  return { status: 'success', result: data };
}

async function performUpdate(data) {
  // Implementation
  return { status: 'updated', data };
}

CLI Commands

# Initialize new instance
openclaw init [name]

# Start gateway
openclaw start

# Start with specific config
openclaw start --config ./custom-config.yml

# Stop gateway
openclaw stop

# Check status
openclaw status

# View logs
openclaw logs

# Plugin management
openclaw plugin install <plugin-name>
openclaw plugin list
openclaw plugin remove <plugin-name>

# Channel management
openclaw channel add telegram
openclaw channel list
openclaw channel enable telegram
openclaw channel disable telegram

# Node management
openclaw node add <node-name> <node-url>
openclaw node list
openclaw node remove <node-name>

# Database migrations
openclaw migrate up
openclaw migrate down
openclaw migrate status

Common Patterns

Multi-Channel Routing

// config/routing.js
export default {
  routes: [
    {
      // Route Telegram messages to specialized agent
      match: { channel: 'telegram' },
      agent: 'telegram-agent',
      sessionKey: 'telegram:{chatId}'
    },
    {
      // Route WhatsApp business inquiries
      match: { 
        channel: 'whatsapp',
        messageContains: ['price', 'product', 'order']
      },
      agent: 'sales-agent',
      sessionKey: 'whatsapp:{phoneNumber}'
    },
    {
      // Default route
      match: {},
      agent: 'main',
      sessionKey: '{channel}:{userId}'
    }
  ]
};

Agent Configuration with Tools

// config/agents/main.js
export default {
  name: 'main',
  description: 'Main assistant agent',
  
  provider: 'anthropic',
  model: 'claude-3-5-sonnet-20241022',
  
  systemPrompt: `You are a helpful AI assistant.
You have access to various tools to help users.
Always be polite and professional.`,
  
  tools: [
    'browser',
    'codeExecution',
    'search',
    'calculator'
  ],
  
  memory: {
    enabled: true,
    maxTokens: 100000,
    summaryThreshold: 80000
  },
  
  temperature: 0.7,
  maxTokens: 4096
};

Context and Memory Management

// Example of accessing context in a plugin
export default async function contextAwareHook(context, next) {
  const { session, memory } = context;
  
  // Retrieve conversation history
  const history = await memory.getHistory(session.id, { limit: 10 });
  
  // Add context to current message
  context.enrichedContext = {
    previousTopics: extractTopics(history),
    userPreferences: await memory.get(`${session.id}:preferences`),
    conversationSummary: await memory.getSummary(session.id)
  };
  
  await next();
  
  // Store important information
  if (context.response.containsImportantInfo) {
    await memory.set(
      `${session.id}:important`,
      context.response.importantInfo,
      { ttl: 86400 * 30 } // 30 days
    );
  }
}

Troubleshooting

Gateway Won't Start

# Check if port is already in use
lsof -i :3000
netstat -an | grep 3000

# Check configuration syntax
openclaw validate-config

# View detailed logs
openclaw start --verbose

# Check database connection
openclaw db:check

Channel Connection Issues

// Enable debug logging for specific channel
// config/channels/telegram.js
export default {
  type: 'telegram',
  enabled: true,
  debug: true, // Enable detailed logging
  config: {
    token: process.env.TELEGRAM_BOT_TOKEN,
    polling: true
  }
};

AI Provider Errors

# Test provider connection
openclaw test-provider anthropic

# Check API key validity
curl -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  https://api.anthropic.com/v1/messages \
  -X POST -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Use fallback provider
# Edit config/ai.js to set fallbackStrategy: 'immediate'

Memory/Performance Issues

# Adjust memory settings in config/gateway.yml
memory:
  enabled: true
  maxTokens: 50000  # Reduce if hitting limits
  provider: redis   # Switch from sqlite for better performance
  redis:
    url: redis://localhost:6379

# Enable compression
compression:
  enabled: true
  algorithm: gzip

# Set rate limits
rateLimit:
  enabled: true
  windowMs: 60000
  maxRequests: 100

Documentation Navigation

Access the full Chinese documentation at: openclaw-docs.dx3n.cn

Key sections:

• Installation: /tutorials/installation/
• Gateway Config: /tutorials/gateway/
• Channel Setup: /tutorials/channels/
• AI Providers: /tutorials/providers/
• Plugin Development: /tutorials/plugins/
• Architecture Deep Dive: /beginner-openclaw-guide/
• AI Framework: /beginner-openclaw-framework-focus/
• Troubleshooting: /tutorials/help/

Resources

• Official OpenClaw: github.com/openclaw
• English Documentation: docs.openclaw.ai
• Chinese Documentation: openclaw-docs.dx3n.cn
• Documentation Repository: github.com/yeuxuan/openclaw-docs