OpenClaw 教程

Appearance

第二部分：快速上手 ​

本部分将带你完成 OpenClaw 的安装、初始化、第一次对话，以及连接第一个消息渠道的全流程实操。

第 3 章：安装与初始化 ​

3.1 前置条件：Node.js 22+ ​

OpenClaw 基于 Node.js 构建，需要 22.0.0 或更高版本。

检查当前 Node.js 版本 ​

bash
node --version

如果输出类似 v22.1.0 或更高版本，可以跳过安装步骤。

安装 Node.js 22 ​

macOS（推荐使用 Homebrew）：

bash
# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node@22

Linux（使用 NodeSource 仓库）：

bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora/RHEL
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

使用 nvm（推荐，支持多版本管理）：

bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重启终端后安装 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

验证安装：

bash
node --version  # 应该显示 v22.x.x
npm --version   # 应该显示 10.x.x 或更高

其他系统依赖 ​

某些功能需要额外的系统工具：

macOS：

bash
# 浏览器自动化需要 Chromium（会自动下载）
# 语音功能需要 ffmpeg
brew install ffmpeg

Linux：

bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y ffmpeg chromium-browser

# Fedora/RHEL
sudo dnf install -y ffmpeg chromium

3.2 一键安装脚本 ​

OpenClaw 提供全自动安装脚本，适用于 macOS 和 Linux。

macOS / Linux 安装 ​

标准安装（推荐）：

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

这个脚本会自动：

  1. 检测系统环境（操作系统、架构、Node.js 版本）
  2. 下载最新版本的 OpenClaw
  3. 安装到全局 npm 目录（/usr/local/bin/openclaw 或 ~/.npm-global/bin/openclaw）
  4. 验证安装成功

查看安装详情（先下载脚本查看内容）：

bash
curl -fsSL https://openclaw.ai/install.sh -o install.sh
cat install.sh  # 检查脚本内容
bash install.sh

指定安装版本：

bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --version 1.2.3

Windows PowerShell 安装 ​

在 PowerShell 中运行（以管理员身份）：

powershell
# 下载安装脚本
Invoke-WebRequest -Uri https://openclaw.ai/install.ps1 -OutFile install.ps1

# 允许执行脚本
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 运行安装
.\install.ps1

注意：Windows 安装会：

  1. 检测并启用 WSL2
  2. 在 WSL2 内安装 Ubuntu
  3. 在 Ubuntu 中安装 OpenClaw

手动安装（通过 npm） ​

如果自动脚本失败，可以手动安装：

bash
# 全局安装
npm install -g openclaw

# 验证安装
openclaw --version

从源码安装（开发者模式）：

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link  # 链接到全局命令

安装路径说明 ​

内容默认路径环境变量覆盖
OpenClaw 主目录~/.openclaw/OPENCLAW_HOME
配置文件~/.openclaw/openclaw.jsonOPENCLAW_CONFIG_PATH
状态文件~/.openclaw/gateway/OPENCLAW_STATE_DIR
智能体数据~/.openclaw/agents/无
日志文件/tmp/openclaw/无

3.3 运行引导向导 ​

安装完成后，运行 引导向导（Onboarding Wizard） 进行初始化配置。

启动向导 ​

bash
openclaw onboard --install-daemon

参数说明：

  • --install-daemon：在 Linux/macOS 上安装 systemd/launchd 守护进程
  • --skip-daemon：仅配置，不安装守护进程
  • --config-only：仅生成配置文件，不启动网关

向导流程 ​

步骤 1：配置认证（API Key / OAuth）

欢迎使用 OpenClaw！
让我们开始配置你的 AI 模型提供商。

你想使用哪个提供商？
  1) Anthropic (Claude)
  2) OpenAI (GPT-4)
  3) Google Gemini
  4) 稍后配置

选择 [1-4]: 1

请输入你的 Anthropic API Key:
sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

✓ API Key 验证成功！

是否要配置额外的提供商？[y/N]: n

支持的认证方式：

提供商认证方式获取地址
AnthropicAPI Keyhttps://console.anthropic.com/settings/keys
OpenAIAPI Keyhttps://platform.openai.com/api-keys
Google GeminiAPI Keyhttps://aistudio.google.com/app/apikey
GroqAPI Keyhttps://console.groq.com/keys
xAIAPI Keyhttps://console.x.ai/
OpenRouterAPI Keyhttps://openrouter.ai/keys

OAuth 订阅认证（可选，支持 Anthropic 和 OpenAI）：

bash
# Anthropic OAuth 登录
openclaw onboard --oauth anthropic

# OpenAI OAuth 登录
openclaw onboard --oauth openai

OAuth 模式的优势：

  • 无需手动管理 API Key
  • 自动使用订阅配额
  • 更安全（Key 不存储在本地）

步骤 2：选择默认模型

请选择默认模型：
  1) claude-opus-4-6 (最强，适合复杂任务)
  2) claude-sonnet-4 (平衡，推荐)
  3) claude-haiku-4 (快速，适合简单任务)
  4) gpt-4-turbo
  5) gemini-2.0-pro

选择 [1-5]: 2

✓ 默认模型设置为 anthropic/claude-sonnet-4

步骤 3：选择智能体工作区

智能体需要一个工作区目录来存储文件和代码。
推荐位置：
  1) ~/openclaw-workspace (推荐)
  2) ~/Documents/OpenClaw
  3) 自定义路径

选择 [1-3]: 1

✓ 工作区创建于：/Users/yourname/openclaw-workspace

工作区会自动创建以下文件：

  • AGENTS.md：智能体操作指引
  • SOUL.md：人格定义
  • IDENTITY.md：身份信息
  • TOOLS.md：工具文档
  • USER.md：用户画像模板

步骤 4：可选配置消息渠道

是否现在配置消息渠道？[y/N]: y

请选择要配置的渠道：
  1) Telegram (最简单，只需 Bot Token)
  2) WhatsApp (需要扫码配对)
  3) Discord (需要创建 Bot 应用)
  4) 稍后配置

选择 [1-4]: 1

请输入 Telegram Bot Token:
(访问 @BotFather 创建机器人并获取 Token)
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

✓ Telegram 机器人连接成功！
  机器人用户名: @your_bot
  机器人 ID: 1234567890

是否配置更多渠道？[y/N]: n

步骤 5：安全配置

设置网关访问安全策略：

1. 网关绑定地址
   - loopback (127.0.0.1, 仅本机访问) [推荐]
   - lan (0.0.0.0, 局域网访问)

选择 [loopback/lan]: loopback

2. 私聊策略
   - pairing (需要配对验证) [推荐]
   - allowlist (仅白名单用户)
   - open (任何人都可以联系)

选择 [pairing/allowlist/open]: pairing

✓ 安全配置完成

步骤 6：完成并启动

配置完成！正在生成配置文件...

✓ 配置文件已保存到：~/.openclaw/openclaw.json
✓ systemd 服务已安装
✓ 网关已启动

下一步：
  1. 访问 Control UI：http://127.0.0.1:18789/
  2. 或运行：openclaw message "Hello!"
  3. 查看状态：openclaw gateway status

运行 "openclaw help" 查看所有可用命令。

非交互式配置 ​

如果你需要自动化部署（如 CI/CD），可以使用环境变量预设配置：

bash
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"
export OPENAI_API_KEY="sk-xxx"
export OPENCLAW_DEFAULT_MODEL="anthropic/claude-sonnet-4"
export OPENCLAW_WORKSPACE="$HOME/workspace"

openclaw onboard --non-interactive --install-daemon

3.4 验证网关状态 ​

配置完成后，验证 OpenClaw Gateway 是否正常运行。

检查网关状态 ​

bash
openclaw gateway status

正常输出示例：

OpenClaw Gateway Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Status:       ✓ Running
Uptime:       2h 34m 12s
PID:          12345
Version:      1.2.3

Network
  Control UI:    http://127.0.0.1:18789/ ✓
  WebSocket:     ws://127.0.0.1:18790/ ✓
  Bind Address:  127.0.0.1 (loopback)

Agents
  Default:       ✓ Active
  Total:         1

Channels
  Telegram:      ✓ Connected (@your_bot)
  WhatsApp:      - Not configured

Memory Usage:    234 MB / 8 GB
CPU Usage:       2.3%

异常状态处理：

状态含义解决方法
✗ Not running网关未启动openclaw gateway start
⚠ Starting...正在启动中等待 10 秒后重试
✗ Error启动失败运行 openclaw doctor --fix
⚠ Degraded部分功能异常检查日志 openclaw logs

检查网关日志 ​

bash
# 查看最近 50 条日志
openclaw logs

# 实时跟踪日志（类似 tail -f）
openclaw logs --follow

# 过滤错误日志
openclaw logs --level error

# 查看特定时间段的日志
openclaw logs --since "2026-02-12 10:00:00"

日志文件位置：

/tmp/openclaw/openclaw-2026-02-12.log

访问 Control UI ​

打开浏览器访问：

http://127.0.0.1:18789/

如果看到 OpenClaw 控制面板，说明网关运行正常。

运行健康检查 ​

bash
openclaw health

输出示例：

Running health checks...

✓ Gateway process is running
✓ Control UI is accessible
✓ WebSocket server is responding
✓ Configuration file is valid
✓ Workspace directory exists
✓ Model provider (Anthropic) is reachable
✓ Memory usage is normal (234 MB)
✓ Disk space is sufficient (45 GB free)

All checks passed!

诊断工具 ​

如果健康检查失败，运行诊断工具：

bash
openclaw doctor --fix

这会自动尝试修复常见问题：

  • 配置文件格式错误
  • 权限问题
  • 端口冲突
  • 依赖缺失

3.5 环境变量配置 ​

OpenClaw 支持通过环境变量覆盖默认配置，适用于容器化部署或多环境管理。

核心环境变量 ​

路径相关：

环境变量默认值说明
OPENCLAW_HOME~/.openclawOpenClaw 主目录
OPENCLAW_STATE_DIR$OPENCLAW_HOME/gateway网关状态文件目录
OPENCLAW_CONFIG_PATH$OPENCLAW_HOME/openclaw.json配置文件路径
OPENCLAW_WORKSPACE配置文件中指定智能体工作区路径

网络相关：

环境变量默认值说明
OPENCLAW_GATEWAY_BIND127.0.0.1网关绑定地址
OPENCLAW_GATEWAY_PORT18789Control UI 端口
OPENCLAW_GATEWAY_WS_PORT18790WebSocket 端口

认证相关：

环境变量说明
ANTHROPIC_API_KEYAnthropic API 密钥
OPENAI_API_KEYOpenAI API 密钥
GOOGLE_API_KEYGoogle Gemini API 密钥
GROQ_API_KEYGroq API 密钥
XAI_API_KEYxAI API 密钥
OPENROUTER_API_KEYOpenRouter API 密钥

日志相关：

环境变量默认值说明
OPENCLAW_LOG_LEVELinfo日志级别：debug / info / warn / error
OPENCLAW_LOG_DIR/tmp/openclaw日志文件目录

使用 .env 文件 ​

在 ~/.openclaw/ 目录下创建 .env 文件：

bash
# ~/.openclaw/.env

# 认证密钥
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 网络配置
OPENCLAW_GATEWAY_BIND=127.0.0.1
OPENCLAW_GATEWAY_PORT=18789

# 默认模型
OPENCLAW_DEFAULT_MODEL=anthropic/claude-sonnet-4

# 工作区路径
OPENCLAW_WORKSPACE=/home/user/workspace

# 日志配置
OPENCLAW_LOG_LEVEL=debug

OpenClaw 会在启动时自动加载 .env 文件。

加载优先级 ​

环境变量的覆盖优先级（从高到低）：

  1. 命令行参数：openclaw gateway start --bind 0.0.0.0
  2. 系统环境变量：export OPENCLAW_GATEWAY_BIND=0.0.0.0
  3. .env 文件：~/.openclaw/.env
  4. 配置文件：openclaw.json 中的设置
  5. 默认值：代码中的默认值

示例：

bash
# 方式 1：直接设置环境变量
export OPENCLAW_LOG_LEVEL=debug
openclaw gateway start

# 方式 2：临时设置（仅本次命令有效）
OPENCLAW_LOG_LEVEL=debug openclaw gateway start

# 方式 3：使用 .env 文件（持久化）
echo "OPENCLAW_LOG_LEVEL=debug" >> ~/.openclaw/.env
openclaw gateway start

Docker 环境变量配置 ​

在 docker-compose.yml 中配置：

yaml
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    environment:
      - OPENCLAW_HOME=/root/.openclaw
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OPENCLAW_DEFAULT_MODEL=anthropic/claude-sonnet-4
      - OPENCLAW_LOG_LEVEL=info
    env_file:
      - .env  # 从外部 .env 文件加载

环境变量替换（配置文件内） ​

在 openclaw.json 配置文件中可以引用环境变量：

json
{
  "auth": {
    "providers": [
      {
        "name": "anthropic",
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    ]
  },
  "agents": {
    "defaults": {
      "workspace": "${HOME}/openclaw-workspace",
      "model": "${OPENCLAW_DEFAULT_MODEL:-anthropic/claude-sonnet-4}"
    }
  }
}

语法说明：

  • ${VAR}：引用环境变量 VAR
  • ${VAR:-default}：如果 VAR 未设置，使用 default 作为默认值

第 4 章：第一次对话 ​

4.1 零配置体验：Control UI ​

OpenClaw 提供 Control UI Web 界面，无需配置消息渠道即可体验智能体对话。

启动 Control UI ​

方式 1：使用 dashboard 命令（推荐）

bash
openclaw dashboard

这会自动：

  1. 启动网关（如果尚未运行）
  2. 打开浏览器访问 http://127.0.0.1:18789/

方式 2：手动访问

bash
# 确保网关正在运行
openclaw gateway status

# 在浏览器中访问
open http://127.0.0.1:18789/  # macOS
xdg-open http://127.0.0.1:18789/  # Linux

Control UI 界面总览 ​

Control UI 主界面包含以下区域：

┌─────────────────────────────────────────────────┐
│  OpenClaw Control                    [设置] [⚙️] │
├─────────────┬───────────────────────────────────┤
│             │                                   │
│  会话列表    │         消息区域                   │
│             │  ┌─────────────────────────────┐ │
│  📝 主会话   │  │ AI: 你好！我是 OpenClaw      │ │
│  🔒 私密会话 │  │     智能助手。有什么可以帮你？ │ │
│  💼 工作会话 │  └─────────────────────────────┘ │
│             │  ┌─────────────────────────────┐ │
│  [+ 新会话]  │  │ 你: 今天天气怎么样？         │ │
│             │  └─────────────────────────────┘ │
│             │  ┌─────────────────────────────┐ │
│             │  │ AI: [正在思考...]           │ │
│             │  └─────────────────────────────┘ │
│             │                                   │
│             │  ┌─────────────────────────────┐ │
│             │  │ 输入消息...                  │ │
│             │  └─────────────────────────────┘ │
│             │  [发送]  📎 附件  🎤 语音        │
├─────────────┴───────────────────────────────────┤
│  模型: claude-sonnet-4  📊 Token: 1.2K  ⚡ 快速 │
└─────────────────────────────────────────────────┘

界面元素说明：

元素功能
会话列表管理多个隔离的对话上下文
消息区域显示历史对话记录
输入框发送文本消息
附件按钮上传图片、文件
语音按钮语音输入（需要麦克风权限）
模型选择器切换不同的 AI 模型
设置按钮配置智能体参数、工具策略

发送第一条消息 ​

在输入框中输入：

你好！请介绍一下你自己。

按 Enter 或点击 发送 按钮。

预期响应：

你好！我是 OpenClaw 智能助手，运行在你的本地设备上。

我的能力包括：
• 💬 多渠道消息处理（WhatsApp、Telegram、Discord 等）
• 🔧 执行命令和操作文件
• 🌐 浏览器自动化和网页抓取
• 📝 记忆系统（记住你的偏好和历史信息）
• 🤖 调用外部工具和 API

我的身份信息存储在工作区的 IDENTITY.md 文件中，
你可以随时修改我的人格设定和行为准则。

有什么我可以帮你的吗？

测试工具调用 ​

尝试让智能体执行一个简单的系统命令：

输入：

请告诉我当前日期和时间。

预期行为：

  1. AI 会使用 exec 工具执行 date 命令
  2. 界面显示工具调用过程：
    [工具调用] exec
┌─────────────────────────┐
│ $ date                  │
└─────────────────────────┘
  3. 返回结果：
    当前日期和时间是：
2026年2月12日 星期三 15:30:42 CST

测试记忆系统 ​

对话 1：

你: 我的名字是张三，我喜欢喝咖啡。
AI: 好的，我记住了！张三，你喜欢咖啡。这个信息已保存到我的记忆中。

对话 2（在新会话或几小时后）：

你: 我喜欢什么饮料？
AI: 根据我的记忆，你（张三）喜欢喝咖啡。

测试多模态输入 ​

上传图片：

  1. 点击 📎 附件按钮
  2. 选择一张图片（如屏幕截图、照片）
  3. 添加描述："这张图片里有什么？"

预期响应：

这张图片显示的是一个网页界面，包含...
[详细的图片描述]

4.2 通过 CLI 发送测试消息 ​

除了 Web 界面，你也可以通过命令行与智能体交互。

发送单条消息 ​

bash
openclaw message "你好，OpenClaw！"

输出：

正在发送消息到主会话...

AI 回复:
你好！很高兴见到你。有什么我可以帮助的吗？

会话 ID: main
消息 ID: msg-1234567890
Token 用量: 45 (输入) + 32 (输出) = 77 总计

交互式对话模式 ​

bash
openclaw message --interactive

进入持续对话模式：

OpenClaw 交互式对话
输入 /exit 退出，/reset 重置会话

你: 今天天气怎么样？
AI: 让我查一下...
    [使用 web_search 工具搜索"今天天气"]

    根据搜索结果，今天北京天气：
    - 温度：-2°C ~ 5°C
    - 天气：多云转晴
    - 风力：北风 3-4 级

你: 谢谢！
AI: 不客气！有其他问题随时问我。

你: /exit
再见！

指定智能体和会话 ​

bash
# 发送到特定智能体
openclaw message --agent work-assistant "整理今天的待办事项"

# 发送到特定会话
openclaw message --session work-project-123 "项目进展如何？"

# 创建新会话
openclaw message --new-session "开始一个全新的对话"

发送带附件的消息 ​

bash
# 发送图片
openclaw message --attach ~/screenshot.png "分析这张图片"

# 发送文件
openclaw message --attach ~/document.pdf "总结这个文档的要点"

# 发送多个附件
openclaw message --attach file1.jpg --attach file2.jpg "比较这两张图片"

使用管道输入 ​

bash
# 从文件读取内容
cat report.txt | openclaw message --stdin "总结这篇文章"

# 从命令输出作为输入
ls -la | openclaw message --stdin "分析这个目录结构"

# 与其他工具组合
curl https://api.github.com/users/octocat | openclaw message --stdin "解释这个 JSON 数据"

4.3 Control UI 界面导览 ​

会话管理 ​

创建新会话：

  1. 点击左侧边栏的 [+ 新会话] 按钮
  2. 输入会话名称（可选）
  3. 新会话会独立存储，与其他会话隔离

切换会话：

  • 在左侧会话列表中点击任意会话名称
  • 每个会话保留独立的对话历史和上下文

重置会话：

  • 右键点击会话 → 选择 重置会话
  • 或在会话中发送 /reset 命令
  • 会话重置后，历史记录清空，但记忆系统保留

删除会话：

  • 右键点击会话 → 选择 删除会话
  • 删除后无法恢复（除非从备份恢复）

消息操作 ​

编辑消息：

  • 鼠标悬停在你的消息上，点击 ✏️ 编辑 按钮
  • 修改后重新发送，AI 会基于新内容重新生成回复

删除消息：

  • 鼠标悬停在消息上，点击 🗑️ 删除 按钮
  • 删除消息会从上下文中移除

复制消息：

  • 点击 📋 复制 按钮，复制消息文本到剪贴板

重新生成回复：

  • 点击 AI 回复下方的 🔄 重新生成 按钮
  • AI 会基于同样的输入重新生成回复（可能不同）

模型切换 ​

切换模型：

  1. 点击底部状态栏的 模型选择器
  2. 选择可用的模型：
    • claude-opus-4-6（最强）
    • claude-sonnet-4（推荐）
    • claude-haiku-4（快速）
    • gpt-4-turbo
    • gemini-2.0-pro

模型对比：

模型优势适用场景
Claude Opus 4.6最强推理能力复杂编程、深度分析、多步骤规划
Claude Sonnet 4平衡性能和成本日常对话、代码审查、内容创作
Claude Haiku 4极快响应速度快速问答、简单任务、批量处理
GPT-4 Turbo知识面广通用问答、数据分析
Gemini 2.0 Pro多模态能力强图片分析、视频理解

设置面板 ​

点击右上角 [⚙️ 设置] 按钮，打开设置面板：

智能体设置：

  • 系统提示词：自定义智能体的行为准则
  • 温度（Temperature）：调整输出的随机性（0.0-1.0）
    • 0.0：确定性输出，适合代码生成
    • 1.0：创意性输出，适合文学创作
  • 最大 Token：限制单次回复的长度

工具策略：

  • 允许的工具：勾选智能体可以使用的工具
  • 沙箱模式：启用 Docker 容器隔离执行
  • 需要确认的工具：指定哪些工具需要人工批准

记忆设置：

  • 启用记忆系统：开启长期记忆功能
  • 记忆搜索提供商：选择向量嵌入模型
  • 自动记忆刷写：在上下文压缩前自动保存记忆

4.4 理解会话（Session）的概念 ​

会话（Session）是 OpenClaw 中对话上下文的基本单位。

主会话 vs 隔离会话 ​

主会话（Main Session）：

  • 每个智能体有一个默认的主会话
  • 会话 ID：main
  • 适用场景：日常对话、个人助手

隔离会话（Isolated Session）：

  • 为特定任务创建的独立会话
  • 会话 ID：自定义（如 work-project-123）
  • 适用场景：
    • 多个独立项目
    • 需要不同上下文的任务
    • 临时性或一次性对话

区别总览：

特性主会话隔离会话
会话 IDmain自定义
记忆加载自动加载 MEMORY.md可选加载
生命周期长期存在可手动删除
重置策略按配置自动重置独立控制

会话生命周期 ​

1. 创建（Creation）：

bash
# CLI 创建新会话
openclaw sessions create --id my-project

# 或在首次发送消息时自动创建
openclaw message --session my-project "开始新项目"

2. 活跃（Active）：

  • 接收和处理消息
  • 累积对话上下文
  • 调用工具和执行任务

3. 空闲（Idle）：

  • 一段时间未收到消息
  • 上下文保留在内存中
  • 触发条件：sessions.idleTimeout（默认 30 分钟）

4. 压缩（Compaction）：

  • 当上下文过长时自动触发
  • 将历史消息总结为摘要
  • 触发条件：
    • Token 数超过阈值（如 100K）
    • 消息数超过限制（如 500 条）

5. 重置（Reset）：

  • 清空对话历史（但保留记忆文件）
  • 触发条件：
    • 手动重置：/reset 命令
    • 定时重置：每日固定时间
    • 空闲重置：闲置 N 分钟后

6. 销毁（Destroy）：

  • 删除会话文件
  • 释放内存资源
  • 触发条件：
    • 手动删除
    • 超过保留期限（默认 30 天）

会话存储结构 ​

每个会话存储在独立的 .jsonl 文件中：

~/.openclaw/agents/default/sessions/
├── main.jsonl           # 主会话
├── work-project.jsonl   # 工作项目会话
└── temp-chat.jsonl      # 临时会话

.jsonl 格式示例：

jsonl
{"role":"user","content":"你好！","timestamp":"2026-02-12T10:00:00Z"}
{"role":"assistant","content":"你好！有什么可以帮你？","timestamp":"2026-02-12T10:00:05Z"}
{"role":"user","content":"今天天气怎么样？","timestamp":"2026-02-12T10:01:00Z"}
{"role":"assistant","content":"让我查一下...","timestamp":"2026-02-12T10:01:02Z"}
{"role":"tool_use","name":"web_search","params":{"query":"今天天气"},"timestamp":"2026-02-12T10:01:03Z"}
{"role":"tool_result","content":"...","timestamp":"2026-02-12T10:01:05Z"}

会话重置策略 ​

在 openclaw.json 中配置：

json
{
  "sessions": {
    "resetPolicy": {
      "mode": "scheduled",  // 模式：scheduled / idle / manual
      "schedule": {
        "time": "04:00",    // 每天凌晨 4 点重置
        "timezone": "Asia/Shanghai"
      }
    },
    "idleTimeout": 1800000  // 30 分钟无活动后重置（毫秒）
  }
}

重置模式对比：

模式说明适用场景
scheduled定时重置（每天固定时间）个人助手（每天开始新对话）
idle空闲重置（N 分钟无活动）临时任务（完成后自动清理）
manual仅手动重置长期项目（保留完整历史）

第 5 章：连接你的第一个消息渠道 ​

5.1 Telegram（最快上手，Bot Token 即可） ​

Telegram 是最容易配置的渠道，只需一个 Bot Token 即可完成接入。

创建 Telegram Bot ​

步骤 1：联系 @BotFather

  1. 在 Telegram 中搜索 @BotFather（官方机器人管理工具）
  2. 发送 /start 开始对话
  3. 发送 /newbot 创建新机器人

步骤 2：设置机器人信息

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

你: OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example: TetrisBot

你: openclaw_assistant_bot

BotFather: Done! Congratulations on your new bot.

           Token: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567

           Use this token to access the HTTP API:
           https://t.me/openclaw_assistant_bot

复制 Token：1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567

配置 OpenClaw ​

方式 1：使用 CLI 引导

bash
openclaw channels add telegram

交互式提示：

请输入 Telegram Bot Token:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567

正在验证 Token...
✓ Bot 信息:
  名称: OpenClaw Assistant
  用户名: @openclaw_assistant_bot
  ID: 1234567890

是否启用私聊？[Y/n]: y
私聊策略 (pairing/allowlist/open): pairing

是否允许群组消息？[y/N]: y
群组策略 - 需要提及才响应？[Y/n]: y

✓ Telegram 渠道配置成功！

方式 2：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

json
{
  "channels": {
    "telegram": [
      {
        "enabled": true,
        "token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz1234567",
        "dm": "pairing",
        "requireMention": true
      }
    ]
  }
}

重启网关：

bash
openclaw gateway restart

验证连接 ​

bash
openclaw channels list

输出：

已配置的渠道:

Telegram
  状态: ✓ 已连接
  机器人: @openclaw_assistant_bot
  私聊策略: pairing
  群组策略: 需要提及

开始对话 ​

  1. 在 Telegram 中搜索你的机器人：@openclaw_assistant_bot
  2. 点击 Start 或发送 /start
  3. 如果启用了 pairing 策略，机器人会要求配对：
OpenClaw Assistant:
你好！我是 OpenClaw 智能助手。

为了安全起见，请输入配对码以验证身份。
如果你是管理员，请在服务器上运行：
  openclaw pairing create

然后使用 /pair <配对码> 命令进行配对。

在服务器上生成配对码：

bash
openclaw pairing create --expire 1h

输出：

配对码已创建:
  代码: ABC123
  有效期: 1 小时
  可用次数: 1 次

在 Telegram 中完成配对：

你: /pair ABC123

OpenClaw Assistant:
✓ 配对成功！你现在可以使用所有功能了。

有什么我可以帮你的吗？

高级配置 ​

允许特定用户（白名单）：

json
{
  "channels": {
    "telegram": [
      {
        "enabled": true,
        "token": "...",
        "dm": "allowlist",
        "allowFrom": [
          "123456789",  // Telegram User ID
          "987654321"
        ]
      }
    ]
  }
}

获取用户 ID： 让用户发送任意消息给机器人，查看日志：

bash
openclaw logs --follow

日志中会显示：

[INFO] Received message from Telegram user 123456789 (@username)

配置多个 Bot：

json
{
  "channels": {
    "telegram": [
      {
        "accountId": "personal",
        "token": "TOKEN_1",
        "dm": "pairing"
      },
      {
        "accountId": "work",
        "token": "TOKEN_2",
        "dm": "allowlist",
        "allowFrom": ["123456789"]
      }
    ]
  }
}

5.2 WhatsApp（QR 码配对，Baileys 协议） ​

WhatsApp 是最流行的消息平台，OpenClaw 使用 Baileys 协议（非官方）进行接入。

配置 WhatsApp ​

方式 1：使用 CLI 引导

bash
openclaw channels add whatsapp

交互式提示：

WhatsApp 配置向导

请选择手机号码归属地：
  1) 中国 (+86)
  2) 美国 (+1)
  3) 其他

选择 [1-3]: 1

你的手机号码（不含国家码）: 13800138000

私聊策略 (pairing/allowlist/open): pairing

是否允许群组消息？[y/N]: y
群组策略 - 需要提及才响应？[Y/n]: y

正在生成配对二维码...

┌────────────────────────────────────┐
│                                    │
│      ████████  ████  ████████      │
│      ██    ██  ████  ██    ██      │
│      ██    ██  ████  ██    ██      │
│      ████████  ████  ████████      │
│                                    │
└────────────────────────────────────┘

请使用 WhatsApp 扫描此二维码：
1. 打开 WhatsApp
2. 点击右上角 ⋮ → 已关联的设备
3. 点击"关联设备"
4. 扫描上方二维码

等待配对...

在手机上完成配对：

  1. 打开 WhatsApp 应用
  2. 进入 设置 → 已关联的设备
  3. 点击 关联设备
  4. 扫描终端显示的二维码

配对成功：

✓ 配对成功！
  手机号: +86 138 0013 8000
  设备名: OpenClaw Gateway
  状态: 已连接

WhatsApp 渠道配置完成！

验证连接 ​

bash
openclaw channels list

输出：

已配置的渠道:

WhatsApp
  状态: ✓ 已连接
  账号: +86 138 0013 8000
  私聊策略: pairing
  群组策略: 需要提及
  最后同步: 2 分钟前

开始对话 ​

私聊：

  1. 在 WhatsApp 中给自己的号码发送消息
  2. 如果启用了 pairing 策略，会提示配对

群组：

  1. 将你的 WhatsApp 号码添加到群组
  2. 在群组中 @提及 你的号码并发送消息
  3. 智能体会响应被提及的消息

常见问题 ​

问题 1：二维码扫描失败

原因：网络连接不稳定或 WhatsApp 服务器限流

解决方法：

bash
# 重新生成二维码
openclaw channels pairing whatsapp --regenerate

问题 2：设备被踢下线

原因：WhatsApp 限制同时关联的设备数（最多 5 个）

解决方法：

  1. 在手机上断开其他已关联设备
  2. 重新扫码配对

问题 3：消息无法发送

原因：账号被 WhatsApp 标记为疑似机器人

解决方法：

  • 减少消息频率（每分钟不超过 10 条）
  • 不要向大量陌生人发送消息
  • 使用备用号码进行测试

高级配置 ​

允许特定联系人（白名单）：

json
{
  "channels": {
    "whatsapp": [
      {
        "enabled": true,
        "dm": "allowlist",
        "allowFrom": [
          "[email protected]",  // 手机号格式
          "[email protected]"
        ],
        "requireMention": true
      }
    ]
  }
}

获取联系人 ID： 让联系人发送消息，查看日志：

bash
openclaw logs --follow

日志中会显示：

[INFO] Received WhatsApp message from [email protected]

5.3 Discord（Bot 应用 + Token） ​

Discord 是社区和游戏玩家首选的平台，OpenClaw 通过 Discord Bot 接入。

创建 Discord Bot 应用 ​

步骤 1：访问 Discord 开发者门户

  1. 打开 Discord Developer Portal
  2. 点击 New Application
  3. 输入应用名称：OpenClaw Bot
  4. 点击 Create

步骤 2：创建 Bot 用户

  1. 在左侧菜单选择 Bot
  2. 点击 Add Bot → 确认 Yes, do it!
  3. 自定义 Bot 信息：
    • Username：OpenClaw
    • Icon：上传头像（可选）

步骤 3：获取 Bot Token

  1. 在 Bot 页面，点击 Reset Token
  2. 复制 Token：MTIzNDU2Nzg5MDEyMzQ1Njc4OTAuGAbCdE.fGHIjKLmNoPqRsTuVwXyZ0123456789
  3. 注意：Token 只显示一次，请妥善保存

步骤 4：启用必要的特权意图（Privileged Gateway Intents）

  1. 在 Bot 页面，向下滚动到 Privileged Gateway Intents
  2. 启用以下选项：
    • ✅ Presence Intent
    • ✅ Server Members Intent
    • ✅ Message Content Intent（重要！用于读取消息内容）
  3. 点击 Save Changes

步骤 5：生成邀请链接

  1. 在左侧菜单选择 OAuth2 → URL Generator
  2. 在 Scopes 中勾选：
    • ✅ bot
    • ✅ applications.commands
  3. 在 Bot Permissions 中勾选：
    • ✅ Read Messages/View Channels
    • ✅ Send Messages
    • ✅ Send Messages in Threads
    • ✅ Embed Links
    • ✅ Attach Files
    • ✅ Read Message History
    • ✅ Add Reactions
  4. 复制生成的 URL（类似 https://discord.com/oauth2/authorize?client_id=...）

步骤 6：邀请 Bot 到服务器

  1. 将复制的 URL 粘贴到浏览器
  2. 选择要添加 Bot 的服务器
  3. 点击 授权 → 完成人机验证

配置 OpenClaw ​

方式 1：使用 CLI 引导

bash
openclaw channels add discord

交互式提示：

请输入 Discord Bot Token:
MTIzNDU2Nzg5MDEyMzQ1Njc4OTAuGAbCdE.fGHIjKLmNoPqRsTuVwXyZ0123456789

正在验证 Token...
✓ Bot 信息:
  名称: OpenClaw
  用户名: OpenClaw#1234
  ID: 1234567890123456789

私聊策略 (pairing/allowlist/open): pairing

是否允许服务器（Guild）消息？[y/N]: y
服务器策略 - 需要提及才响应？[Y/n]: y

✓ Discord 渠道配置成功！

方式 2：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

json
{
  "channels": {
    "discord": [
      {
        "enabled": true,
        "token": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTAuGAbCdE.fGHIjKLmNoPqRsTuVwXyZ0123456789",
        "dm": "pairing",
        "requireMention": true
      }
    ]
  }
}

重启网关：

bash
openclaw gateway restart

验证连接 ​

bash
openclaw channels list

输出：

已配置的渠道:

Discord
  状态: ✓ 已连接
  机器人: OpenClaw#1234
  私聊策略: pairing
  服务器策略: 需要提及
  已加入服务器: 3 个

开始对话 ​

私聊：

  1. 在 Discord 中找到你的 Bot 用户（OpenClaw#1234）
  2. 发送私聊消息
  3. 如果启用了 pairing 策略，Bot 会提示配对

服务器（频道）：

  1. 在任意文字频道中 @提及 Bot：@OpenClaw 你好！
  2. Bot 会响应被提及的消息

高级配置 ​

绑定特定服务器到特定智能体：

json
{
  "agents": {
    "list": [
      {
        "id": "gaming-bot",
        "model": "anthropic/claude-haiku-4",
        "bindings": [
          {
            "channel": "discord",
            "guildId": "987654321098765432"  // 服务器 ID
          }
        ]
      },
      {
        "id": "work-bot",
        "model": "anthropic/claude-sonnet-4",
        "bindings": [
          {
            "channel": "discord",
            "guildId": "123456789012345678"
          }
        ]
      }
    ]
  }
}

获取服务器 ID：

  1. 在 Discord 中启用开发者模式：设置 → 高级 → 开发者模式
  2. 右键点击服务器图标 → 复制 ID

5.4 渠道通用概念 ​

DM 策略（Direct Message Strategy） ​

控制智能体如何处理私聊消息。

策略说明适用场景安全性
pairing需要配对验证个人助手、私人部署⭐⭐⭐ 高
allowlist仅白名单用户团队协作、已知用户⭐⭐⭐ 高
open任何人都可以联系公开服务、演示机器人⭐ 低（不推荐）
disabled禁用私聊仅服务于群组/服务器⭐⭐ 中

配置示例：

json
{
  "channels": {
    "telegram": [
      {
        "dm": "pairing"  // 默认推荐
      }
    ]
  }
}

群组消息：requireMention 提及门控 ​

控制智能体在群组中的行为。

启用提及门控（推荐）：

json
{
  "channels": {
    "telegram": [
      {
        "requireMention": true  // 只有被 @ 时才响应
      }
    ]
  }
}

行为对比：

requireMention行为优势劣势
true只响应被 @ 的消息不干扰群聊、减少误触发需要手动提及
false响应所有消息对话更自然可能打扰群聊、消耗 Token

示例：

# requireMention: true
用户A: 今天天气真好
      [智能体不响应]

用户B: @OpenClaw 今天天气怎么样？
智能体: 让我查一下...

# requireMention: false
用户A: 今天天气真好
智能体: 是的，今天天气确实不错！
      [可能不希望的行为]

allowFrom 白名单机制 ​

限制只有特定用户可以与智能体交互。

配置示例：

json
{
  "channels": {
    "telegram": [
      {
        "dm": "allowlist",
        "allowFrom": [
          "123456789",    // Telegram User ID
          "987654321"
        ]
      }
    ],
    "whatsapp": [
      {
        "dm": "allowlist",
        "allowFrom": [
          "[email protected]",  // WhatsApp JID
          "[email protected]"
        ]
      }
    ],
    "discord": [
      {
        "dm": "allowlist",
        "allowFrom": [
          "234567890123456789"  // Discord User ID
        ]
      }
    ]
  }
}

动态添加到白名单：

bash
# 添加用户到 Telegram 白名单
openclaw channels allowlist add telegram 111222333

# 列出所有白名单用户
openclaw channels allowlist list telegram

# 移除用户
openclaw channels allowlist remove telegram 111222333

小结 ​

通过本章学习，你应该已经完成：

  1. 安装与初始化：

    • ✅ 安装 Node.js 22+
    • ✅ 运行 openclaw onboard 配置智能体
    • ✅ 验证网关状态和健康检查
    • ✅ 理解环境变量配置

  2. 第一次对话：

    • ✅ 通过 Control UI 与智能体交互
    • ✅ 使用 CLI 发送消息
    • ✅ 理解会话的概念和生命周期

  3. 连接消息渠道：

    • ✅ Telegram：最快上手（Bot Token）
    • ✅ WhatsApp：QR 码配对（Baileys 协议）
    • ✅ Discord：Bot 应用接入
    • ✅ 掌握 DM 策略、提及门控、白名单机制

接下来，我们将在 第三部分：核心概念深入 中，深入学习智能体运行时、会话管理、记忆系统、模型提供商配置等高级主题。

参考文档：

  • start/getting-started — 快速入门指南
  • channels/telegram — Telegram 渠道配置
  • channels/whatsapp — WhatsApp 渠道配置
  • channels/discord — Discord 渠道配置
  • concepts/session — 会话管理概念