环境搭建与配置

2.1 系统要求与准备工作

在开始安装 OpenClaw 之前，让我们先确保你的环境满足基本要求。好消息是：OpenClaw 的资源需求非常友好，大多数现代设备都能轻松运行。

2.1.1 硬件要求

2.1.2 操作系统支持

2.1.3 软件依赖

OpenClaw 的安装脚本会自动处理大部分依赖，但了解这些依赖有助于故障排查：

1. Node.js（必需）
   • 版本要求：Node.js 18.0 或更高版本
   • 推荐：Node.js 20 LTS
   • 包管理器：npm 或 pnpm（推荐 pnpm，更快更节省空间）
2. Git（可选但推荐）
   • 用于源码安装和更新
   • 大多数系统已预装
3. cURL（必需）
   • 用于下载安装脚本
   • 几乎所有系统都已预装
4. Bash/Zsh（必需）
   • macOS/Linux默认已安装
   • Windows 需要使用 Git Bash 或 WSL

2.1.4 AI 模型 API 准备

OpenClaw 需要一个 AI 模型作为"大脑"来驱动。你需要提前准备至少一个模型的 API Key：

2.1.5 通信渠道准备

OpenClaw 通过你常用的通信工具与你交互。选择一个你最常用的平台：

• Telegram（最推荐）：配置简单，功能强大，隐私性好
• Discord：适合开发者，支持丰富的机器人功能
• WhatsApp：全球最普及，但配置稍复杂
• Slack：适合工作场景，团队协作
• Signal：极致隐私保护
• iMessage：苹果生态用户首选（仅 macOS）
• 飞书/钉钉/企业微信：国内企业用户

2.2 快速安装指南

OpenClaw 提供了多种安装方式，从一键安装到源码编译，满足不同用户的需求。我们将从最简单的方式开始。

# 打开终端，执行以下命令：
curl -fsSL https://openclaw.ai/install.sh | bash

# 以管理员身份打开 PowerShell，执行：
irm https://openclaw.ai/install.ps1 | iex

🦞 OpenClaw installed successfully!

Next steps:
1. Run 'openclaw onboard' to set up your assistant
2. Choose your AI model provider
3. Connect your preferred chat app
4. Start chatting!

# 全局安装 OpenClaw
npm install -g openclaw

# 验证安装
openclaw --version

# 启动 onboarding
openclaw onboard

# 全局安装
pnpm add -g openclaw

# 验证安装
openclaw --version

# 启动 onboarding
openclaw onboard

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 创建数据卷（持久化存储）
docker volume create openclaw-data

# 运行容器
docker run -d \
  --name openclaw \
  -v openclaw-data:/app/data \
  -p 3000:3000 \
  -e OPENCLAW_DATA_DIR=/app/data \
  --restart unless-stopped \
  openclaw/openclaw:latest

# 查看日志
docker logs -f openclaw

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    ports:
      - "3000:3000"
    environment:
      - OPENCLAW_DATA_DIR=/app/data
      - NODE_ENV=production
    restart: unless-stopped

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 启动 onboarding
pnpm run openclaw onboard

# 或者链接到全局
pnpm link --global
openclaw onboard

2.2.2 安装过程详解

让我们深入了解一键安装脚本都做了些什么：

1. 系统检测
   • 识别操作系统类型和版本
   • 检查架构（x86_64 / arm64）
   • 检测已安装的依赖
2. 依赖安装
   • 如果没有 Node.js，会通过 Homebrew（macOS）或 apt/yum（Linux）安装
   • 确保 npm/pnpm 可用
   • 安装必要的系统工具（如必要）
3. OpenClaw 安装
   • 通过 npm 安装 openclaw 包
   • 创建配置文件目录（~/.openclaw）
   • 设置环境变量
4. 权限配置
   • 设置文件权限
   • 配置 PATH 环境变量
   • 创建 shell 补全脚本

2.2.3 验证安装是否成功

安装完成后，运行以下命令验证：

# 检查版本号
openclaw --version

# 应该输出类似：openclaw/1.2.3 darwin-arm64 node-v20.11.0

# 检查帮助信息
openclaw --help

# 检查配置目录
ls -la ~/.openclaw

# 应该看到：
# config.json
# data/
# logs/
# skills/

2.3 初始配置流程

安装完成后，我们需要进行初始配置。OpenClaw 提供了一个友好的交互式 onboarding 流程，引导你完成所有必要设置。

openclaw onboard

🦞 Welcome to OpenClaw!

This setup will help you configure your personal AI assistant.
Let's get started!

Press ENTER to continue...

? Choose your AI model provider:
❯ Anthropic (Claude) - Best for complex tasks
  OpenAI (GPT-4) - Great tool ecosystem
  MiniMax - Free tier available, fast in China
  Kimi (Moonshot) - Long context, Chinese optimized
  Zhipu AI (GLM) - Cost-effective
  Local Model (Ollama) - Fully offline
  Skip for now (configure later)

? Enter your Anthropic API Key: sk-ant-...

✓ API Key validated successfully!
✓ Claude 3.5 Sonnet selected as your default model

? Choose your communication channel:
❯ Telegram - Easy setup, powerful features
  Discord - Great for developers
  WhatsApp - Most popular globally
  Slack - Best for teams
  Signal - Maximum privacy
  iMessage - Apple ecosystem (macOS only)
  Skip for now (use CLI only)

? You chose Telegram! Let's set it up.

Step 1: Open Telegram and search for @BotFather
Step 2: Send /newbot command
Step 3: Follow BotFather's instructions to create a bot
Step 4: Copy the Bot Token (looks like: 123456:ABC-DEF...)

? Enter your Bot Token: [hidden]

✓ Bot token validated!
✓ Your bot is ready to use

Now, start a chat with your bot in Telegram:
1. Search for your bot's username
2. Send /start
3. Come back here and press ENTER

? Have you started chatting with your bot? Yes

✓ Telegram channel configured successfully!

? What would you like to name your assistant?
Default: Claw

> Jarvis

? Describe your assistant's personality in a few words:
Default: Helpful, efficient, and professional

> Friendly, proactive, and detail-oriented. Like a helpful colleague.

? What's your name?

> Alex

✓ Persona configured!

Your assistant Jarvis knows:
- Your name is Alex
- Should be friendly, proactive, and detail-oriented
- Will act like a helpful colleague

? Choose security level:
❯ Balanced (Recommended) - Good balance of power and safety
  Maximum Security - Sandboxed execution, limited access
  Full Access - Complete system control (advanced users only)

You chose: Balanced

With this setting, OpenClaw can:
✓ Read and write files in your home directory
✓ Execute safe shell commands
✓ Access the internet
✓ Control your browser

But cannot:
✗ Modify system files
✗ Install software without confirmation
✗ Access other users' files

? Is this okay? Yes

? Enable persistent memory? (Recommended)

This allows Jarvis to remember:
- Your preferences and habits
- Context from previous conversations
- Important information you share
- Completed tasks and ongoing projects

? Enable memory? Yes

? Memory retention period:
❯ Keep everything (unlimited)
  Keep last 6 months
  Keep last 30 days
  Keep last 7 days

You chose: Keep everything

✓ Memory system enabled!

? Enable heartbeat (proactive checks)?

Heartbeat allows Jarvis to:
- Check for pending tasks every 30 minutes
- Send you reminders and updates
- Proactively suggest actions
- Run scheduled tasks

? Enable heartbeat? Yes

? Heartbeat interval:
❯ Every 30 minutes (Recommended)
  Every hour
  Every 2 hours
  Only when I ask

You chose: Every 30 minutes

Active hours (when heartbeat runs):
Default: 08:00 - 22:00 (your local timezone)

? Adjust active hours? No

✓ Heartbeat configured!

🎉 Setup complete! Here's your configuration summary:

Assistant Name: Jarvis
Your Name: Alex
AI Model: Claude 3.5 Sonnet (Anthropic)
Communication: Telegram (@JarvisAlexBot)
Security Level: Balanced
Memory: Enabled (unlimited)
Heartbeat: Every 30 minutes (08:00-22:00)

Configuration saved to: ~/.openclaw/config.json

What's next?
1. Send a message to your bot on Telegram
2. Try: "Hi Jarvis, what can you do?"
3. Check out the documentation: docs.openclaw.ai

Need help? Join our community: discord.gg/openclaw

Happy clawing! 🦞

2.3.2 配置文件详解

Onboarding 完成后，你的配置会保存在 ~/.openclaw/config.json。让我们看看这个文件的结构：

{
  "assistant": {
    "name": "Jarvis",
    "persona": "Friendly, proactive, and detail-oriented. Like a helpful colleague.",
    "user_name": "Alex"
  },
  "models": {
    "default": "anthropic",
    "providers": {
      "anthropic": {
        "enabled": true,
        "api_key": "sk-ant-...",
        "default_model": "claude-3-5-sonnet-20241022"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "bot_token": "123456:ABC-DEF...",
      "webhook_url": "https://your-domain.com/webhook/telegram"
    }
  },
  "security": {
    "level": "balanced",
    "allowed_paths": ["/Users/alex"],
    "blocked_commands": ["sudo", "rm -rf /"]
  },
  "memory": {
    "enabled": true,
    "retention_days": null,
    "encryption": true
  },
  "heartbeat": {
    "enabled": true,
    "interval_minutes": 30,
    "active_hours": {
      "start": "08:00",
      "end": "22:00"
    }
  },
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log"
  }
}

2.4 验证安装

配置完成后，让我们进行一些测试，确保一切正常工作。

2.4.1 首次对话测试

打开你配置的通信渠道（以 Telegram 为例），发送第一条消息：

You: Hi Jarvis, what can you do?

Jarvis: Hi Alex! 👋 I'm your personal AI assistant. Here's what I can help you with:

📋 Task Management
- Create and manage to-do lists
- Set reminders and deadlines
- Track your progress

📧 Email & Communication
- Read and organize emails
- Draft responses
- Manage subscriptions

📁 File Operations
- Search and organize files
- Convert formats
- Extract information from documents

🌐 Web Tasks
- Browse websites
- Extract data
- Monitor changes

💻 Development
- Write and review code
- Run tests
- Manage Git repositories

And much more! Just ask me to do something, and I'll take care of it.

What would you like me to help you with today?

2.4.2 基础功能验证

让我们测试几个核心功能：

测试 1：简单问答

You: What's the weather like today?

Jarvis: Let me check that for you...

[Checks weather API]

Today in San Francisco:
🌤️ Partly cloudy
🌡️ Temperature: 18°C (64°F)
💨 Wind: 15 km/h NW
💧 Humidity: 65%

Perfect weather for a walk! Would you like me to remind you to go outside this afternoon?

测试 2：文件操作

You: Can you show me my recent documents?

Jarvis: Sure! Here are your recently modified documents:

📄 Project_Proposal.docx - 2 hours ago
📊 Q1_Report.pdf - yesterday
📝 Meeting_Notes.txt - 2 days ago
📈 Budget_2026.xlsx - 3 days ago

Would you like me to open any of these or search for something specific?

测试 3：任务创建

You: Remind me to call John tomorrow at 3pm

Jarvis: ✓ Reminder created!

📅 Task: Call John
⏰ Time: Tomorrow at 3:00 PM
🔔 Notification: I'll remind you via Telegram 10 minutes before

Anything else you'd like me to remember?

测试 4：网页浏览

You: What are the top stories on Hacker News?

Jarvis: Let me fetch that for you...

[Browses news.ycombinator.com]

Top stories on Hacker News right now:

1. OpenClaw becomes #1 trending project on GitHub
   523 points | 187 comments
   
2. Show HN: I built a tool to automate my entire workflow
   412 points | 98 comments
   
3. The Future of AI Agents
   389 points | 156 comments

Want me to summarize any of these articles?

2.4.3 心跳机制测试

等待 30 分钟（或者在你配置的下一个心跳时间），你应该会收到主动消息：

Jarvis: 🔔 Afternoon Check-in

Hi Alex! Just checking in. Here's what I noticed:

✅ Completed today:
- Responded to 12 emails
- Organized your Downloads folder
- Created 3 reminders

⏰ Upcoming:
- Call with John in 10 minutes (as requested)
- Team meeting at 4:00 PM

💡 Suggestion:
I noticed you have several unread newsletters. Would you like me to summarize them for you?

Just let me know if you need anything!

2.4.4 命令行工具测试

除了聊天界面，OpenClaw 还提供了强大的 CLI 工具：

# 查看助手状态
openclaw status

# 输出：
🦞 OpenClaw Status
━━━━━━━━━━━━━━━━━━━━━
Assistant: Jarvis (running)
Model: Claude 3.5 Sonnet
Uptime: 2h 34m
Memory Usage: 423 MB
Tasks Today: 15
Last Activity: 2 minutes ago

# 查看任务列表
openclaw tasks list

# 创建新任务
openclaw tasks add "Review PR #123" --due "tomorrow 10am"

# 查看日志
openclaw logs --tail 50

# 重新加载配置
openclaw reload

# 停止助手
openclaw stop

# 启动助手
openclaw start

2.4.5 故障排查

如果测试过程中遇到问题，可以按照以下步骤排查：

1. 检查进程状态

   # 查看 OpenClaw 是否在运行
   ps aux | grep openclaw
   
   # 或者使用 systemctl（Linux）
   systemctl status openclaw

2. 查看日志文件

   # 实时查看日志
   tail -f ~/.openclaw/logs/openclaw.log
   
   # 或者使用 CLI
   openclaw logs --level error

3. 测试 API 连接

   # 测试 AI 模型连接
   openclaw test-model
   
   # 测试通信渠道
   openclaw test-channel telegram

4. 重启服务

   # 完全重启
   openclaw restart
   
   # 或者手动
   openclaw stop
   openclaw start

2.5 高级安装选项

对于有特殊需求的用户，OpenClaw 提供了更多高级安装和配置选项。

2.5.1 多实例部署

你可以运行多个 OpenClaw 实例，用于不同的用途（如工作/个人分离）：

# 创建工作实例
OPENCLAW_HOME=~/.openclaw-work openclaw onboard

# 配置时命名为 "Work Assistant"
# 配置工作相关的通信渠道和权限

# 启动工作实例
OPENCLAW_HOME=~/.openclaw-work openclaw start

# 启动个人实例（默认）
openclaw start

# 查看运行中的实例
openclaw instances

# 输出：
🦞 Running Instances
━━━━━━━━━━━━━━━━━━━━━━━━━
1. default (~/.openclaw) - Personal
   Status: running, Uptime: 5h 23m

2. work (~/.openclaw-work) - Work
   Status: running, Uptime: 2h 11m

2.5.2 自定义构建配置

如果你需要从源码定制构建：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 复制配置模板
cp .env.example .env

# 编辑 .env 文件，自定义配置
cat > .env << EOF
NODE_ENV=development
OPENCLAW_PORT=3000
OPENCLAW_DATA_DIR=~/.openclaw-custom
LOG_LEVEL=debug
ENABLE_DEBUG_TOOLS=true
CUSTOM_SKILLS_PATH=~/my-skills
EOF

# 安装依赖
pnpm install

# 自定义构建
pnpm run build:custom

# 运行
pnpm run dev

2.5.3 云服务器部署

将 OpenClaw 部署到云服务器，实现 24/7 在线：

方案一：VPS 部署（以 Ubuntu 为例）

# SSH 连接到服务器
ssh user@your-server.com

# 一键安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 配置 systemd 服务
sudo nano /etc/systemd/system/openclaw.service

# 添加以下内容：
[Unit]
Description=OpenClaw AI Assistant
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/home/your-user
ExecStart=/usr/bin/openclaw start
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

# 查看状态
sudo systemctl status openclaw

方案二：Docker 部署到云容器

# 在云服务商控制台创建容器实例
# 以 AWS ECS 为例：

# 创建任务定义
cat > task-definition.json << EOF
{
  "family": "openclaw",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "2048",
  "containerDefinitions": [
    {
      "name": "openclaw",
      "image": "openclaw/openclaw:latest",
      "portMappings": [
        {
          "containerPort": 3000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "NODE_ENV",
          "value": "production"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/openclaw",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}
EOF

# 注册任务定义
aws ecs register-task-definition --cli-input-json file://task-definition.json

# 创建服务
aws ecs create-service --cluster openclaw-cluster --service-name openclaw --task-definition openclaw --desired-count 1

2.5.4 本地模型集成

如果你希望完全离线运行，可以集成本地 AI 模型：

使用 Ollama

# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 拉取模型
ollama pull llama3.1:8b

# 配置 OpenClaw 使用 Ollama
openclaw config models add ollama \
  --base-url http://localhost:11434 \
  --model llama3.1:8b

# 设置为默认模型
openclaw config models default ollama

# 测试
openclaw test-model

使用 LM Studio

# 下载并安装 LM Studio
# 下载喜欢的模型（如 Qwen2.5-7B-Instruct）
# 启动本地服务器（默认端口 1234）

# 配置 OpenClaw
openclaw config models add lmstudio \
  --base-url http://localhost:1234/v1 \
  --model qwen2.5-7b-instruct

# 启用
openclaw config models default lmstudio

2.5.5 企业级部署考虑

对于企业环境，还需要考虑以下方面：

• 高可用性：使用负载均衡 + 多实例
• 数据备份：定期备份 ~/.openclaw/data 目录
• 监控告警：集成 Prometheus + Grafana
• 审计日志：开启详细日志并发送到 SIEM 系统
• 网络隔离：部署在内网，通过反向代理暴露必要端口
• 密钥管理：使用 Vault 或云厂商 KMS 管理 API Keys

# 企业级 Docker Compose 示例
version: '3.8'

services:
  openclaw-1:
    image: openclaw/openclaw:latest
    deploy:
      replicas: 3
    environment:
      - NODE_ENV=production
      - REDIS_URL=redis://redis:6379
    volumes:
      - shared-data:/app/data
    depends_on:
      - redis
      - postgres

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl

volumes:
  shared-data:
  redis-data:
  postgres-data:

2.6 本章小结