基于 OpenClaw 官方文档整理的结构化教学文档
版本：2026.3.1
更新日期：2026-03-01

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

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

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

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

# macOS/Linux curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)

iwr -useb https://openclaw.ai/install.ps1 | iex

讯享网openclaw onboard –install-daemon

向导会自动配置：

• ✅ 认证（API Key）
• ✅ 网关设置
• ✅ 可选频道

openclaw gateway status

讯享网# 启动 Dashboard openclaw dashboard

或直接访问

open http://127.0.0.1:18789

运行以下命令验证：

# 检查版本 openclaw –version

检查状态

openclaw status

发送测试消息

openclaw message send –target + –message “Hello OpenClaw!”

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

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

Session 是一次对话的上下文：

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

Agent 是 AI 助手的执行者：

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

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

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

OpenClaw 使用 WebSocket 进行所有通信：

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

• IRC、LINE、Matrix、Nextcloud Talk、Nostr、Twitch 等

讯享网# 方法 1：使用向导（推荐） openclaw onboard

方法 2：手动配置

1. 生成 Gateway token

openclaw gateway create-token

2. 在手机上配对

扫描二维码或输入配对代码

3. 测试连接

openclaw message send –target + –message “Test”

# 1. 创建 Bot

访问 @BotFather，创建新 Bot

2. 获取 Token

复制 Bot Token

3. 配置 OpenClaw

4. 测试

openclaw message send –channel telegram –message “Hello Telegram!”

讯享网# 1. 创建 Bot 和应用

访问 Discord Developer Portal

2. 获取 Bot Token 和 Client ID

3. 配置 OpenClaw

4. 配置 Intents

需要启用：MESSAGE_CONTENT, MESSAGE_READ, SERVERS

5. 测试

openclaw message send –channel discord –message “Hello Discord!”

┌─────────────────────────────────────┐ │ Messaging Apps │ │ (WhatsApp/Telegram/Discord) │ └─────────────┬───────────────────┘

讯享网 │ WebSocket │ ┌─────────▼──────────┐ │ Gateway │ │ (single daemon) │ └─────────┬──────────┘ │ ┌────────▼────────┐ │ Provider APIs │ │ (Anthropic/OpenAI)│ └─────────┬────────┘ │ ┌────────▼──────┐ │ AI Agents │ │ (Claude/GPT) │ └────────────────┘</code></pre></div><ul><li data-pid="KSICmsLT">📡 维持 Provider 连接</li><li data-pid="gISCidxb">🎯 处理会话和路由</li><li data-pid="oIiozzMu">🔧 管理工具调用</li><li data-pid="37mgjaF5">📊 提供健康检查和监控</li></ul><ul><li data-pid="brKe1mFq">🖥️ <b>macOS App</b>：原生应用，完整功能</li><li data-pid="NmP_ux31">💻 <b>CLI</b>：命令行工具，自动化友好</li><li data-pid="YI7LT1mx">🌐 <b>WebChat</b>：网页聊天界面</li><li data-pid="HFUD7otJ">📱 <b>iOS/Android Nodes</b>：移动端支持</li></ul><ul><li data-pid="7tf5TEKV">🔐 所有客户端通过 WebSocket 连接到 Gateway</li><li data-pid="a9pi83Ld">📍 默认地址：<code>127.0.0.1:18789</code></li><li data-pid="cTKlseoq">🔒 支持通过 Tailscale/VPN 远程访问</li></ul><hr/><table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>工具</th><th>功能</th><th>用途</th></tr><tr><td>read</td><td>读取文件内容</td><td>配置文件、代码读取</td></tr><tr><td>write</td><td>写入文件</td><td>创建新文件、保存结果</td></tr><tr><td>edit</td><td>编辑文件</td><td>精确替换文件内容</td></tr><tr><td>apply_patch</td><td>结构化补丁</td><td>多文件批量编辑</td></tr></tbody></table><table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>工具</th><th>功能</th><th>用途</th></tr><tr><td>sessions_list</td><td>列出会话</td><td>查看所有活跃会话</td></tr><tr><td>sessions_history</td><td>会话历史</td><td>获取过往消息</td></tr><tr><td>sessions_send</td><td>发送消息</td><td>跨会话通信</td></tr><tr><td>sessions_spawn</td><td>创建新会话</td><td>启动子 Agent</td></tr><tr><td>session_status</td><td>会话状态</td><td>检查会话健康度</td></tr></tbody></table><table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>工具</th><th>功能</th><th>用途</th></tr><tr><td>memory_search</td><td>语义搜索</td><td>查找相关记忆</td></tr><tr><td>memory_get</td><td>获取记忆</td><td>读取特定记忆片段</td></tr></tbody></table><table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>工具</th><th>功能</th><th>用途</th></tr><tr><td>web_search</td><td>网页搜索</td><td>使用 Brave 搜索 API</td></tr><tr><td>web_fetch</td><td>网页提取</td><td>HTML → Markdown</td></tr></tbody></table><table data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal"><tbody><tr><th>工具</th><th>功能</th><th>用途</th></tr><tr><td>browser</td><td>浏览器控制</td><td>自动化网页操作</td></tr><tr><td>canvas</td><td>Canvas 展示</td><td>可视化展示内容</td></tr><tr><td>screenshot</td><td>截图</td><td>捕获页面状态</td></tr></tbody></table><div class="highlight"><pre><code class="language-text">{ 

“tools”: {

"allow": ["read", "write", "browser"], "deny": ["exec"] 

} }

讯享网{ “tools”: {

"profile": "coding" 

} }

预定义配置文件：

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

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

配置步骤：

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

使用效果：

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

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

配置步骤：

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

配置示例：

讯享网{ “channels”: {

"discord": { "groups": { "*": { "requireMention": true } } }, "slack": { "allowFrom": ["U", "U0"] } 

} }

使用效果：

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

场景： 不同 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 使用编辑工具撰写报告

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

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)</code></pre></div><p data-pid="L09tXX9F"><b>场景：</b> AI 记住用户的偏好和历史</p><p data-pid="EyokKwrW"><b>记忆配置：</b></p><div class="highlight"><pre><code class="language-text">{ 

“memory”: {

讯享网"enabled": true, "search": { "enabled": true }, "store": { "onReply": true, "onMessage": true } 

} }

使用示例：

1. 用户： “我不吃辣”
   
   

• Agent 存储到记忆

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

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

1. 用户： “我最近在学什么？”
   
   

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

场景： AI 自动化网页操作

浏览器工具使用：

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

2. 导航到登录页

讯享网"kind": "click", "ref": "login-button" 

}’

3. 填写表单

"kind": "fill", "ref": "username-input", "text": "my-username" 

}’

4. 提交表单

讯享网"kind": "click", "ref": "submit-button" 

}’

高级：截图 + 分析

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

2. 分析页面内容

讯享网"kind": "evaluate", "fn": "document.querySelector(\"h1\").textContent" 

}’

3. 基于分析导航

"kind": "navigate", "url": "https://next-page.com" 

}’

讯享网# 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": ["+"] }, "discord": { "botToken": "your-bot-token", "clientId": "your-client-id", "clientSecret": "your-client-secret" }, "whatsapp": { "gatewayToken": "your-gateway-token", "allowFrom": ["+"], "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"] } } 

} }

{ ”agents“: {

讯享网"list": [ { "id": "support", "tools": { "byProvider": { "openai/gpt-4": { "allow": ["message", "sessions_list"] } } } } ] 

} }

症状：

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

症状：

# 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

症状：

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“]‘

症状：

# 频繁掉线 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

症状：

# 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

{ ”tools“: {

讯享网"loopDetection": { "enabled": true, "warningThreshold": 10, "criticalThreshold": 20 } 

} }

作用： 防止 Agent 陷入死循环

{ ”gateway“: {

讯享网"streaming": { "enabled": true, "chunkSize": 1000 } 

} }

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

{ ”gateway“: {

讯享网"cache": { "responses": { "enabled": true, "ttl": 900 } } 

} }

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

• 📖 OpenClaw 官网
• 📚 文档主页
• 📖 GitHub 仓库
• 💬 问题反馈

• 🤖 Anthropic API
• 🤖 OpenAI API
• 💻 Pi 架构
• 🔧 工具参考
• 📱 频道文档

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

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

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

祝使用愉快！🎉