OpenClaw 简介

1.1 什么是 OpenClaw

OpenClaw（原名 Clawdbot，后更名 Moltbot，2025 年 1 月正式定名）是一个开源的本地 AI 智能体框架。它可以运行在自有服务器或电脑上，数据完全自主可控，支持多种平台接入。

1.2 主要特性

• 本地部署：数据完全本地，隐私安全
• 多平台支持：飞书、Telegram、Discord、WhatsApp 等
• 浏览器控制：可浏览网页、填写表单、提取数据
• 系统访问：读写文件、执行 Shell 命令、运行脚本
• 持久化记忆：记住用户偏好和交互上下文

1.3 推荐配置

项目	推荐配置
操作系统	macOS（功能最完整）/ Linux / Windows
Node.js	v22.x 或更高
内存	8GB+（推荐）/ 4GB（最低）
IM 工具	飞书（国内）/ Telegram（国外）
AI 模型	通义千问（免费）/ Claude / OpenAI

2. 环境准备

2.1 安装 Node.js

OpenClaw 要求 Node.js 版本 ≥ 22.x，推荐使用 NVM（Node 版本管理器）安装。

macOS/Linux 用户

# 安装 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source ~/.bashrc

# 安装 Node.js 22
nvm install 22

# 验证版本
node -v  # 输出 v22.x.x
npm -v

Windows 用户

方法一：访问 https://nodejs.org/ 下载 LTS 版本安装包

方法二：使用 WSL2（推荐）

# 在 PowerShell 中运行
wsl --install

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

2.2 准备 AI API Key

OpenClaw 需要配置 AI 模型服务商，以下是几种常见选择：

服务商	特点	获取方式
通义千问 (Qwen)	免费额度充足，适合中文	https://dashscope.aliyun.com
Anthropic (Claude)	推理能力强	https://console.anthropic.com
OpenAI (GPT)	功能全面	https://platform.openai.com
Kimi	国内友好	https://platform.moonshot.cn

⚠️ 请妥善保管 API Key，勿将其提交到公开仓库或分享给他人！

3. OpenClaw 安装

3.1 一键安装（推荐）

使用官方提供的一键安装脚本：

macOS/Linux

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

Windows

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

3.2 npm 全局安装

# 安装最新版
npm install -g openclaw@latest

# 或安装指定版本（推荐 2026.4.14 稳定版）
npm install -g openclaw@2026.4.14 --force

# 验证安装
openclaw --version

3.3 安装飞书插件

OpenClaw 通过插件机制支持飞书，需要单独安装：

# 方式一：使用 openclaw 命令
openclaw plugins install @openclaw/feishu

# 方式二：npm 全局安装
npm install -g @openclaw/feishu

# 方式三：pnpm
pnpm add -g @openclaw/feishu

💡 Windows 用户建议使用 npm 全局安装方式，兼容性更好。

4. 初始化配置

4.1 运行新手引导

安装完成后，运行新手引导进行初始化配置：

openclaw onboard --install-daemon

引导会引导你完成：

1. 安全风险确认（选择 Yes 继续）
2. 配置模式选择（推荐 QuickStart 快速配置）
3. AI 模型服务商选择（如 Qwen OAuth）
4. API Key 配置或 OAuth 授权
5. Gateway 运行模式设置

4.2 通义千问 OAuth 配置（推荐）

如果选择通义千问，按以下步骤操作：

1. 选择 Qwen OAuth 后，控制台会生成授权链接和验证码
2. 复制授权链接在本地浏览器打开
3. 登录阿里云账号，输入验证码完成授权
4. 返回终端按回车继续

5. 飞书 Bot 配置

5.1 创建飞书应用

1. 访问飞书开放平台：https://open.feishu.cn/app
2. 登录并点击「创建企业自建应用」
3. 填写应用名称（如「AI 助手」）
4. 选择应用类型为「企业自建应用」

5.2 获取应用凭证

在应用详情页的「凭证与基础信息」中获取：

字段	说明	格式示例
App ID	应用唯一标识	cli_xxxxxxxxxxxx
App Secret	应用密钥（只显示一次）	xxxxxxxxxxxxxxxx

⚠️ App Secret 只会显示一次，请立即复制保存！如果遗失需要重新生成。

5.3 配置应用权限

进入「权限管理」，点击「批量导入」，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot",
      "im:chat",
      "im:chat:members:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.group_msg"
    ],
    "user": [
      "im:message.p2p_msg:readonly"
    ]
  }
}

5.4 启用机器人能力

• 进入「应用能力」 → 「机器人」
• 开启「机器人能力」开关
• 设置机器人显示名称

5.5 配置事件订阅

进入「事件订阅」，选择「使用长连接接收事件」（WebSocket 模式）：

• 添加事件：接收消息 v2.0 (im.message.receive_v2)
• 保存配置

5.6 发布应用

• 进入「版本管理与发布」
• 创建版本 → 填写版本说明 → 提交
• 等待审批（企业内部应用通常自动通过）

5.7 配置 OpenClaw

将飞书应用的凭证配置到 OpenClaw，有三种方式：

方式一：通过向导配置（推荐）

openclaw onboard

在配置过程中选择飞书渠道，按提示输入 App ID 和 App Secret。

方式二：通过环境变量

export FEISHU_APP_ID=cli_xxxxxxxxxxxx
export FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx

# Windows PowerShell
$env:FEISHU_APP_ID="cli_xxxxxxxxxxxx"
$env:FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"

方式三：通过配置文件

编辑 ~/.openclaw/config.json：

{
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxx"
    }
  }
}

6. 启动与测试

6.1 启动 Gateway

# 查看服务状态
openclaw gateway status

# 手动启动
openclaw gateway start

# 后台运行
openclaw gateway start --daemon

6.2 访问控制台

启动后访问 http://localhost:3000 查看 Web 控制台，可以：

• 查看 Gateway 状态
• 管理渠道配置
• 查看日志和调试信息
• 管理配对码

6.3 测试飞书机器人

1. 在飞书中搜索并添加创建的机器人
2. 发送消息进行测试
3. 如果收到回复，说明配置成功

💡 首次使用需要输入配对码（pairing code），在 Web 控制台查看或运行 openclaw pairing code 获取。

6.4 在群组中使用

• 将机器人添加到飞书群组
• @机器人名称 发送消息即可触发回复
• 也可以设置机器人为群管理员获得更多权限

7. 常见问题解决

7.1 Node.js 版本问题

错误信息：Node version is too old

# 解决方法：升级到 Node 22+
nvm install 22
nvm use 22

7.2 安装失败

如果 npm 安装失败，尝试使用 --force 参数：

npm install -g openclaw@2026.4.14 --force

7.3 权限问题

macOS 用户可能需要授予系统权限：

• 辅助功能（无障碍访问）
• 文件夹访问权限
• 屏幕录制权限

7.4 飞书机器人无响应

可能原因	解决方法
应用未发布	确保应用已提交审批并通过
权限不足	检查已开启 im:message 等必要权限
Gateway 未启动	运行 openclaw gateway start
配置错误	检查 App ID 和 App Secret 是否正确

7.5 WSL2 网络问题

Windows WSL2 用户如果遇到网络连接问题：

# 在 PowerShell 管理员模式下运行
wsl --shutdown

# 重新启动 WSL2
wsl

8. 命令速查表

8.1 安装与配置

命令	说明
openclaw --version	查看版本
openclaw onboard	运行新手引导
openclaw plugins install @openclaw/feishu	安装飞书插件
openclaw plugins list	列出已安装插件

8.2 Gateway 管理

命令	说明
openclaw gateway start	启动 Gateway
openclaw gateway start --daemon	后台运行
openclaw gateway stop	停止 Gateway
openclaw gateway status	查看状态
openclaw gateway logs	查看日志

8.3 配对码管理

命令	说明
openclaw pairing code	获取配对码
openclaw pairing list	列出已配对设备
openclaw pairing revoke <id>	撤销配对

8.4 配置文件位置

系统	配置路径
macOS	~/.openclaw/config.json
Linux	~/.openclaw/config.json
Windows	%USERPROFILE%\.openclaw\config.json