OpenClaw 入门指南与实战案例合集

FT305
165 阅读11分钟

OpenClaw 入门指南与实战案例合集

基于 OpenClaw 官方文档整理的结构化教学文档

版本：2026.3.1
更新日期：2026-03-01

📚 目录

  1. OpenClaw 简介
  2. 快速开始
  3. 核心概念
  4. 功能特性
  5. 聊天频道
  6. 架构原理
  7. 工具系统
  8. 实战案例
  9. 高级配置
  10. 故障排查

🎯 1. OpenClaw 简介

什么是 OpenClaw？

OpenClaw 是一个自托管的网关服务，将你常用的聊天应用（WhatsApp、Telegram、Discord、iMessage 等）连接到 AI 编程助手（如 Claude）。

核心价值

  • ✅ 自托管：运行在你自己的硬件上，数据完全掌控
  • ✅ 多频道支持：一个网关同时服务 WhatsApp、Telegram、Discord、iMessage 等
  • ✅ Agent 原生：专为 AI Agent 设计，支持工具使用、会话管理、记忆、多 Agent 路由
  • ✅ 开源：MIT 许可证，社区驱动
  • ✅ 5 分钟上手：Node 22+、API key（推荐 Anthropic）

适用人群

  • 🛠️ 开发者：需要个人 AI 助手，不依赖托管服务
  • 👨‍💻 高级用户：希望掌控自己的数据和工作流
  • 🏢 团队协作：多成员、多频道的统一管理

🚀 2. 快速开始

前置要求

要求说明
Node.js22+
API KeyAnthropic 推荐
操作系统macOS、Linux、Windows (WSL2)
时间约 5 分钟

快速安装步骤

步骤 1：安装 OpenClaw
# macOS/Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex
步骤 2：运行向导配置
openclaw onboard --install-daemon

向导会自动配置：

  • ✅ 认证（API Key）
  • ✅ 网关设置
  • ✅ 可选频道
步骤 3：检查网关状态
openclaw gateway status
步骤 4：启动控制界面
# 启动 Dashboard
openclaw dashboard

# 或直接访问
open http://127.0.0.1:18789

验证安装

运行以下命令验证：

# 检查版本
openclaw --version

# 检查状态
openclaw status

# 发送测试消息
openclaw message send --target +15555550123 --message "Hello OpenClaw!"

🧠 3. 核心概念

Gateway（网关）

Gateway 是 OpenClaw 的核心组件，负责：

  • 🔗 连接聊天应用（WhatsApp、Telegram、Discord 等）
  • 📡 消息路由
  • 🔧 管理会话、工具调用
  • 🚀 提供统一的 WebSocket API

Session（会话）

Session 是一次对话的上下文：

  • 📝 每个 Session 有独立的上下文
  • 🔄 同一会话内的消息会共享上下文
  • 💾 会话结束后自动归档
  • 🏢 Groups（群组）中的会话相互隔离

Agent（代理）

Agent 是 AI 助手的执行者：

  • 🤖 可以使用工具（文件操作、网络请求、浏览器等）
  • 🎯 有明确的任务和权限
  • 🔄 支持多 Agent 协作
  • 🧠 可以有不同的能力和配置

Memory（记忆）

Memory 提供持久化的上下文存储：

  • 📚 可以跨会话保留信息
  • 🔍 支持语义搜索
  • 💾 分为长期记忆和短期记忆

WebSocket 协议

OpenClaw 使用 WebSocket 进行所有通信：

  • 📡 客户端 → Gateway：发送请求
  • 📡 Gateway → 客户端：返回响应
  • 🔐 通过 auth token 验证
  • 📦 JSON 格式消息

⭐ 4. 功能特性

核心功能

功能说明
多频道支持WhatsApp、Telegram、Discord、iMessage 等
消息路由智能路由到正确的会话
媒体支持图片、音频、文档的收发
多 Agent 路由按工作区或发送者隔离会话
分组支持群聊隔离，mention 激活
流式输出长回复的分块传输
重试策略网络中断自动重试
命令队列异步任务管理

安全功能

功能说明
设备配对设备注册 + 批准
Allowlist 控制指定允许的联系人和群组
Group 限制群聊需要 mention 才能激活
会话隔离Groups 会话完全隔离
OAuth 认证Anthropic、OpenAI 的官方认证

📱 5. 聊天频道

支持的频道

即时通讯
频道协议特点配置难度
WhatsAppBaileys Web最流行，支持媒体⭐⭐⭐ 需 QR 配对
TelegramBot API (grammY)支持群组、频道⭐⭐ 简单（Bot Token）
DiscordDiscord Bot API支持服务器、频道⭐⭐ 中等（Bot 配置）
Signalsignal-cli注重隐私⭐⭐⭐⭐ 复杂
iMessageimsg CLI (macOS)本地集成⭐⭐⭐⭐ macOS 专用
协作平台
频道协议特点配置难度
SlackBolt SDK企业支持⭐⭐⭐⭐ Bot 配置
MattermostBot API + WebSocket开源替代⭐⭐⭐⭐ 插件
Microsoft TeamsBot Framework企业级⭐⭐⭐⭐⭐ Bot 配置
FeishuLark Bot (WebSocket)企业协作⭐⭐ 简单
其他平台
  • IRC、LINE、Matrix、Nextcloud Talk、Nostr、Twitch 等

快速配置指南

WhatsApp 配置（最复杂）
# 方法 1：使用向导（推荐）
openclaw onboard

# 方法 2：手动配置
# 1. 生成 Gateway token
openclaw gateway create-token

# 2. 在手机上配对
# 扫描二维码或输入配对代码

# 3. 测试连接
openclaw message send --target +15555550123 --message "Test"
Telegram 配置（最简单）
# 1. 创建 Bot
# 访问 @BotFather，创建新 Bot

# 2. 获取 Token
# 复制 Bot Token

# 3. 配置 OpenClaw
openclaw configure --channel telegram \
  --token "your-bot-token-here" \
  --allow-from "+15555550123"

# 4. 测试
openclaw message send --channel telegram --message "Hello Telegram!"
Discord 配置
# 1. 创建 Bot 和应用
# 访问 Discord Developer Portal

# 2. 获取 Bot Token 和 Client ID

# 3. 配置 OpenClaw
openclaw configure --channel discord \
  --bot-token "your-bot-token" \
  --client-id "your-client-id" \
  --client-secret "your-client-secret"

# 4. 配置 Intents
# 需要启用：MESSAGE_CONTENT, MESSAGE_READ, SERVERS

# 5. 测试
openclaw message send --channel discord --message "Hello Discord!"

🏗️ 6. 架构原理

组件架构

┌─────────────────────────────────────┐
│         Messaging Apps          │
│  (WhatsApp/Telegram/Discord) │
└─────────────┬───────────────────┘
              │ WebSocket
              │
    ┌─────────▼──────────┐
    │     Gateway        │
    │  (single daemon)  │
    └─────────┬──────────┘
              │
     ┌────────▼────────┐
     │   Provider APIs   │
     │ (Anthropic/OpenAI)│
     └─────────┬────────┘
               │
    ┌────────▼──────┐
    │   AI Agents   │
    │ (Claude/GPT)  │
    └────────────────┘

关键组件

Gateway（守护进程）
  • 📡 维持 Provider 连接
  • 🎯 处理会话和路由
  • 🔧 管理工具调用
  • 📊 提供健康检查和监控
Clients（客户端）
  • 🖥️ macOS App：原生应用，完整功能
  • 💻 CLI：命令行工具，自动化友好
  • 🌐 WebChat：网页聊天界面
  • 📱 iOS/Android Nodes：移动端支持
节点连接
  • 🔐 所有客户端通过 WebSocket 连接到 Gateway
  • 📍 默认地址：127.0.0.1:18789
  • 🔒 支持通过 Tailscale/VPN 远程访问

🔧 7. 工具系统

工具分类

文件系统（group:fs）
工具功能用途
read读取文件内容配置文件、代码读取
write写入文件创建新文件、保存结果
edit编辑文件精确替换文件内容
apply_patch结构化补丁多文件批量编辑
会话管理（group:sessions）
工具功能用途
sessions_list列出会话查看所有活跃会话
sessions_history会话历史获取过往消息
sessions_send发送消息跨会话通信
sessions_spawn创建新会话启动子 Agent
session_status会话状态检查会话健康度
记忆管理（group:memory）
工具功能用途
memory_search语义搜索查找相关记忆
memory_get获取记忆读取特定记忆片段
Web 工具（group:web）
工具功能用途
web_search网页搜索使用 Brave 搜索 API
web_fetch网页提取HTML → Markdown
UI 工具（group:ui）
工具功能用途
browser浏览器控制自动化网页操作
canvasCanvas 展示可视化展示内容
screenshot截图捕获页面状态

工具配置

全局允许/拒绝
{
  "tools": {
    "allow": ["read", "write", "browser"],
    "deny": ["exec"]
  }
}
按配置文件（profile）
{
  "tools": {
    "profile": "coding"
  }
}

预定义配置文件：

  • minimal：仅 session_status
  • coding：文件系统、运行时、会话、记忆、图片
  • messaging：消息相关工具
  • full：无限制

💡 8. 实战案例

案例 1：个人 AI 助手

场景： 通过 WhatsApp 和 Telegram 使用 Claude 进行日常对话

配置步骤：

  1. 安装 OpenClaw
  2. 配置 WhatsApp（QR 配对）
  3. 配置 Telegram（Bot Token）
  4. 设置 Anthropic API Key

使用效果：

  • ✅ 多渠道统一对话
  • ✅ 上下文在 WhatsApp 和 Telegram 间共享
  • ✅ 支持发送图片、文档
  • ✅ 数据完全在本地

案例 2：团队协作助手

场景： 团队使用 Discord 和 Slack 共享一个 AI 助手

配置步骤：

  1. 配置 Discord Bot
  2. 配置 Slack App
  3. 设置 Group 规则：需要 mention 才激活

配置示例：

{
  "channels": {
    "discord": {
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    },
    "slack": {
      "allowFrom": ["U1234567890", "U0987654321"]
    }
  }
}

使用效果：

  • ✅ 团队成员通过 Discord 提问机器人
  • ✅ Slack 成员通过 allowlist 控制
  • ✅ 群聊会话完全隔离
  • ✅ 记录完整的使用日志

案例 3：多 Agent 任务分配

场景： 不同 Agent 负责不同任务

Agent 配置：

{
  "agents": {
    "list": [
      {
        "id": "coder",
        "tools": {
          "profile": "coding"
        }
      },
      {
        "id": "researcher",
        "tools": {
          "allow": ["web_search", "web_fetch", "read"]
        }
      },
      {
        "id": "writer",
        "tools": {
          "allow": ["write", "edit"]
        }
      }
    ]
  }
}

工作流程：

  1. 用户请求："写一个 Python 脚本处理 Excel"
  2. 主 Agent 识别任务，分配给 coder Agent
  3. coder Agent 使用文件工具完成任务
  4. 用户请求："搜索最新的 AI 趋势"
  5. 主 Agent 分配给 researcher Agent
  6. researcher Agent 使用 Web 工具搜索信息
  7. 用户请求："写一份报告"
  8. 主 Agent 分配给 writer Agent
  9. writer Agent 使用编辑工具撰写报告

案例 4：自动化工作流

场景： 定时任务 + 条件触发

Cron 配置：

{
  "cron": [
    {
      "schedule": "0 9 * * *",
      "task": "morning-briefing"
    },
    {
      "schedule": "0 18 * * *",
      "task": "daily-summary"
    }
  ]
}

任务脚本：

# morning-briefing.py
def morning_briefing():
    # 搜索新闻
    news = search_ai_news()
    
    # 生成简报
    brief = generate_briefing(news)
    
    # 发送到 Telegram
    send_to_telegram(brief)

案例 5：记忆增强对话

场景： AI 记住用户的偏好和历史

记忆配置：

{
  "memory": {
    "enabled": true,
    "search": {
      "enabled": true
    },
    "store": {
      "onReply": true,
      "onMessage": true
    }
  }
}

使用示例：

  1. 用户： "我不吃辣"

    • Agent 存储到记忆

  2. 用户（2 周后）： "帮我推荐个餐厅"

    • Agent 搜索记忆："不辣"
    • Agent 返回：不辣的餐厅推荐

  3. 用户： "我最近在学什么？"

    • Agent 搜索记忆
    • Agent 返回：最近的学习记录

案例 6：浏览器自动化

场景： AI 自动化网页操作

浏览器工具使用：

# 1. 打开网页
openclaw browser open --url "https://example.com"

# 2. 导航到登录页
openclaw browser act \
  --ref "login-button" \
  --request '{
    "kind": "click",
    "ref": "login-button"
  }'

# 3. 填写表单
openclaw browser act \
  --ref "username-input" \
  --request '{
    "kind": "fill",
    "ref": "username-input",
    "text": "my-username"
  }'

# 4. 提交表单
openclaw browser act \
  --ref "submit-button" \
  --request '{
    "kind": "click",
    "ref": "submit-button"
  }'

高级：截图 + 分析

# 1. 截取当前页面
openclaw browser screenshot

# 2. 分析页面内容
openclaw browser act \
  --request '{
    "kind": "evaluate",
    "fn": "document.querySelector(\"h1\").textContent"
  }'

# 3. 基于分析导航
openclaw browser act \
  --request '{
    "kind": "navigate",
    "url": "https://next-page.com"
  }'

🔧 9. 高级配置

环境变量

# OpenClaw 配置目录
export OPENCLAW_HOME="/custom/path"

# 状态目录
export OPENCLAW_STATE_DIR="/custom/state"

# 配置文件路径
export OPENCLAW_CONFIG_PATH="/custom/config.json"

配置文件结构

{
  "channels": {
    "telegram": {
      "token": "your-bot-token",
      "allowFrom": ["+15555550123"]
    },
    "discord": {
      "botToken": "your-bot-token",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    },
    "whatsapp": {
      "gatewayToken": "your-gateway-token",
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": {
          "requireMention": false
        }
      }
    }
  },
  "tools": {
    "profile": "coding",
    "allow": ["group:fs", "group:sessions", "group:memory"],
    "deny": ["exec", "process"]
  },
  "agents": {
    "list": [
      {
        "id": "assistant",
        "model": "openai/gpt-4",
        "tools": {
          "profile": "full"
        }
      }
    ]
  },
  "memory": {
    "enabled": true,
    "search": {
      "enabled": true
    }
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "tls": {
      "enabled": false
    }
  }
}

工具策略配置

按提供商限制
{
  "tools": {
    "byProvider": {
      "openai/gpt-4": {
        "profile": "minimal"
      },
      "google-antigravity": {
        "allow": ["web_search", "web_fetch"]
      }
    }
  }
}
Agent 级别覆盖
{
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": {
          "byProvider": {
            "openai/gpt-4": {
              "allow": ["message", "sessions_list"]
            }
          }
        }
      }
    ]
  }
}

🐛 10. 故障排查

常见问题

问题 1：Gateway 无法启动

症状：

openclaw gateway status
# Error: Gateway is not running

解决方法：

# 1. 检查端口占用
netstat -tuln | grep 18789

# 2. 查看 Gateway 日志
journalctl -u openclaw-gateway -n 50

# 3. 重新启动
openclaw gateway restart

# 4. 如果是权限问题
sudo openclaw gateway restart
问题 2：频道连接失败

症状：

# WhatsApp: 提示 "Not paired"
# Telegram: 发送消息无响应
# Discord: Bot 不在线

WhatsApp 解决方法：

# 1. 重新配对
openclaw whatsapp unpair
openclaw whatsapp pair

# 2. 检查 Gateway token
openclaw gateway status

# 3. 检查网络
ping wa.me

Telegram 解决方法：

# 1. 验证 Bot Token
# 访问 @BotFather，检查 Bot 状态

# 2. 检查 Token 配置
openclaw status | grep telegram

# 3. 测试连接
openclaw message send --channel telegram --message "Test"

Discord 解决方法：

# 1. 检查 Intents
# 访问 Discord Developer Portal

# 2. 验证 Bot 权限
# 需要：MESSAGE_CONTENT, MESSAGE_READ, SERVERS

# 3. 检查服务器配置
openclaw status | grep discord
问题 3：工具调用被拒绝

症状：

Agent: I'm sorry, I cannot use the browser tool.

解决方法：

# 检查工具策略
openclaw status

# 方法 1：全局允许
openclaw configure tools.allow '["browser"]'

# 方法 2：按配置文件允许
openclaw configure tools.profile "full"

# 方法 3：Agent 级别覆盖
openclaw configure agents.list[].tools.allow '["browser"]'
问题 4：WebSocket 连接断开

症状：

# 频繁掉线
openclaw gateway status
# 显示大量连接重连

解决方法：

# 1. 检查网络稳定性
ping api.anthropic.com

# 2. 检查 Gateway 配置
openclaw configure gateway.keepalive true

# 3. 检查 TLS 配置
openclaw configure gateway.tls.enabled true

# 4. 使用远程访问（Tailscale）
tailscale up
问题 5：内存占用过高

症状：

# Gateway 进程占用大量内存
top | grep openclaw-gateway
# 显示 > 1GB 使用量

解决方法：

# 1. 启用会话修剪
openclaw configure session.pruning.enabled true

# 2. 限制历史记录长度
openclaw configure session.history.maxMessages 100

# 3. 启用压缩
openclaw configure gateway.compression.enabled true

# 4. 重启 Gateway
openclaw gateway restart

📊 性能优化建议

1. 工具使用优化

{
  "tools": {
    "loopDetection": {
      "enabled": true,
      "warningThreshold": 10,
      "criticalThreshold": 20
    }
  }
}

作用： 防止 Agent 陷入死循环

2. 流式输出优化

{
  "gateway": {
    "streaming": {
      "enabled": true,
      "chunkSize": 1000
    }
  }
}

作用： 优化长回复的传输效率

3. 缓存配置

{
  "gateway": {
    "cache": {
      "responses": {
        "enabled": true,
        "ttl": 900
      }
    }
  }
}

作用： 缓存常见查询响应，减少 API 调用

🔗 资源链接

官方文档

相关资源

📝 总结

关键要点

  1. ✅ 5 分钟上手：安装 → 配置 → 使用
  2. 🔧 灵活配置：支持多频道、多 Agent、工具策略
  3. 🚀 高性能：流式输出、缓存、压缩
  4. 🔒 安全可靠：OAuth 认证、设备配对、会话隔离
  5. 🌐 全平台支持：WhatsApp、Telegram、Discord、iMessage 等
  6. 🧠 Agent 原生：专为 AI Agent 设计的工具系统
  7. 💾 记忆系统：持久化上下文，跨会话保留信息
  8. 🔌 自动化：Cron、Webhook、多 Agent 协作

下一步

  1. 📖 阅读完整文档：docs.openclaw.ai
  2. 🚀 实战练习：先从单频道、单 Agent 开始
  3. 🔧 探索高级配置：多 Agent 路由、工具策略
  4. 💡 优化性能：启用缓存、流式输出、会话修剪
  5. 🤝 参与社区：GitHub Issues、Discord 社区

版本信息： 2026.3.1
整理日期： 2026-03-01
文档来源： OpenClaw 官方文档

祝使用愉快！🎉

avatar
文章
阅读
粉丝