# OpenClaw + 飞书 部署指南
> 本文档基于 Windows 11 + WSL2 (Ubuntu) 环境下的实际部署过程整理，使用智谱 GLM 作为 AI 模型。适用于 OpenClaw 2026.5.29 及以上版本。
---
## 一、环境要求
| 组件 | 要求 |
|------|------|
| 操作系统 | Windows 10/11 (WSL2) 或 Linux / macOS |
| Node.js | v22.19+（推荐 v24+） |
| npm | v11+ |
| Git | 需要安装 |
| 飞书 | 飞书开放平台账号 |
---
## 二、安装 WSL2（仅 Windows）
以**管理员身份**打开 PowerShell：
```powershell
wsl --install
```
安装完成后重启电脑。
如需将 WSL 迁移到其他盘（比如 E 盘）：
```powershell
wsl --shutdown
wsl --manage Ubuntu --move "E:\WSL\Ubuntu"
```
进入 WSL：
```powershell
wsl -d Ubuntu
```
---
## 三、安装 OpenClaw
### 3.1 一键安装
在 WSL / Linux / macOS 终端中运行：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
如果想跳过引导（稍后手动配置）：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
### 3.2 验证安装
```bash
openclaw --version
```
正常输出类似：`OpenClaw 2026.6.1`
### 3.3 PATH 问题排查
如果 `openclaw` 命令找不到：
```bash
npm config get prefix
```
确保输出的路径在 PATH 中。需要的话在 `~/.bashrc` 末尾添加：
```bash
export PATH="$HOME/.npm-global/bin:$PATH"
```
然后执行：
```bash
source ~/.bashrc
```
---
## 四、配置 AI 模型（智谱 GLM）
> **获取 API 密钥：** 前往 [智谱开放平台](https://open.bigmodel.cn) 注册账号 → API Keys → 创建新的 API Key。
### 方式一：交互式引导
```bash
openclaw onboard
```
选择 `zai-api-key` 或 `custom-api-key`，按提示输入密钥。
### 方式二：非交互式（推荐）
```bash
openclaw onboard --non-interactive \
--accept-risk \
--auth-choice custom-api-key \
--custom-base-url "https://open.bigmodel.cn/api/paas/v4/" \
--custom-model-id "zai/glm-5.1" \
--custom-api-key "你的智谱API密钥" \
--custom-compatibility openai
```
---
## 五、启动 Gateway
### 5.1 安装为系统服务（推荐，开机自启）
```bash
openclaw gateway restart --install-daemon
```
### 5.2 前台运行（调试用）
```bash
openclaw gateway run --port 18789
```
### 5.3 验证状态
```bash
openclaw gateway status
```
正常输出关键信息：
```
Runtime: running (pid xxxx, state active, sub running)
Connectivity probe: ok
Listening: 127.0.0.1:18789
```
---
## 六、飞书开放平台配置
### 6.1 创建飞书自建应用
1. 登录 [飞书开放平台](https://open.feishu.cn/app)
2. 点击 **「创建企业自建应用」**
3. 填写应用名称和描述，创建应用
### 6.2 记录应用凭证
进入应用详情页，记录：
- **App ID**（格式：`cli_xxx`）
- **App Secret**
### 6.3 开启机器人能力
进入 **「应用能力」→「机器人」**，开启机器人能力。
### 6.4 配置事件订阅
1. 进入 **「事件与回调」→「事件配置」**
2. 添加事件：**`im.message.receive_v1`**（接收消息）
3. 连接方式选择 **「使用长连接接收事件」**（WebSocket 模式，**无需公网 IP**）
### 6.5 申请权限
进入 **「权限管理」**，申请以下权限：
| 权限 | 权限标识 | 用途 |
|------|---------|------|
| 获取与发送单聊、群组消息 | `im:message` | 核心功能 |
| 获取群组消息（只读） | `im:message:readonly` | 读取群消息 |
| 获取与上传图片或文件资源 | `im:resource` | 多媒体消息 |
| 获取群组信息 | `im:chat` | 群聊功能 |
| 获取用户基本信息 | `contact:user.base:readonly` | 识别用户 |
### 6.6 发布应用
1. 进入 **「版本管理与发布」**
2. 创建版本并提交审核
3. 管理员在飞书管理后台审批通过
---
## 七、OpenClaw 接入飞书
### 方式一：交互式配置（推荐新手）
```bash
openclaw channels login --channel feishu
```
选择「手动配置」，粘贴 App ID 和 App Secret。
### 方式二：手动编辑配置文件
编辑 `~/.openclaw/openclaw.json`，添加 `channels` 和 `plugins` 字段：
```json
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_你的AppID",
"appSecret": "你的AppSecret",
"connectionMode": "websocket",
"domain": "feishu",
"dmPolicy": "open",
"allowFrom": ["*"],
"groupPolicy": "allowlist"
}
},
"plugins": {
"entries": {
"feishu": {
"enabled": true
}
}
}
}
```
### 配置字段说明
| 字段 | 说明 | 可选值 |
|------|------|--------|
| `connectionMode` | 连接方式 | `websocket`（推荐）/ `webhook` |
| `domain` | 飞书域名 | `feishu`（国内）/ `lark`（国际） |
| `dmPolicy` | 私聊策略 | `open` / `allowlist` / `pairing` / `disabled` |
| `allowFrom` | 允许的用户列表 | `["*"]`（所有人）/ `["ou_xxx"]`（指定用户） |
| `groupPolicy` | 群聊策略 | `open` / `allowlist` / `disabled` |
| `requireMention` | 群聊是否需要@机器人 | `true`（默认）/ `false` |
### 重启 Gateway 使配置生效
```bash
openclaw gateway restart
```
---
## 八、配对认证（仅 pairing 模式）
如果 `dmPolicy` 设为 `pairing`，用户首次私聊机器人时会收到配对码，需要在终端批准：
```bash
# 查看待批准的配对请求
openclaw pairing list feishu
# 批准配对
openclaw pairing approve feishu <配对码>
```
---
## 九、验证是否成功
1. 在飞书中搜索并找到你的机器人
2. 发送一条消息，如「你好」
3. 检查是否收到 AI 回复
4. 如有问题查看日志：
```bash
openclaw logs --follow
```
---
## 十、完整配置文件示例
`~/.openclaw/openclaw.json` 完整示例：
```json
{
"agents": {
"defaults": {
"workspace": "/home/你的用户名/.openclaw/workspace",
"models": {
"zai/glm-5.1": {
"alias": "GLM"
}
},
"model": {
"primary": "zai/glm-5.1"
}
}
},
"gateway": {
"mode": "local",
"auth": {
"mode": "token",
"token": "你的Gateway Token"
},
"port": 18789,
"bind": "loopback"
},
"session": {
"dmScope": "per-channel-peer"
},
"tools": {
"profile": "coding",
"web": {
"search": {
"provider": "duckduckgo",
"enabled": true
}
}
},
"models": {
"mode": "merge",
"providers": {
"zai": {
"baseUrl": "https://open.bigmodel.cn/api/paas/v4",
"api": "openai-completions",
"models": [
{
"id": "glm-5.1",
"name": "GLM-5.1",
"reasoning": true,
"input": ["text"],
"cost": {
"input": 1.2,
"output": 4,
"cacheRead": 0.24,
"cacheWrite": 0
},
"contextWindow": 202800,
"maxTokens": 131100
}
]
}
}
},
"plugins": {
"entries": {
"feishu": { "enabled": true },
"zai": { "enabled": true },
"duckduckgo": { "enabled": true }
}
},
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_你的AppID",
"appSecret": "你的AppSecret",
"connectionMode": "websocket",
"domain": "feishu",
"dmPolicy": "open",
"allowFrom": ["*"],
"groupPolicy": "allowlist"
}
},
"auth": {
"profiles": {
"zai:default": {
"provider": "zai",
"mode": "api_key"
}
}
}
}
```
---
## 十一、常用运维命令
| 命令 | 说明 |
|------|------|
| `openclaw gateway status` | 查看 Gateway 状态 |
| `openclaw gateway restart` | 重启 Gateway |
| `openclaw logs --follow` | 实时查看日志 |
| `openclaw doctor --fix` | 诊断并自动修复问题 |
| `openclaw update` | 更新 OpenClaw |
| `openclaw --version` | 查看版本 |
| `openclaw tui` | 打开终端聊天界面 |
---
## 十二、常见问题排查
### ❌ 机器人不回复私聊消息
1. 检查 Gateway 是否运行：`openclaw gateway status`
2. 查看日志：`openclaw logs --follow`
3. 确认飞书应用已发布并审批通过
4. 确认事件订阅包含 `im.message.receive_v1`
5. 确认选择了「长连接」模式
6. 确认所有权限已申请并审批通过
### ❌ 群聊中机器人不回复
1. 确认机器人已加入群聊
2. 确认在群里 **@了机器人**（默认必须 @）
3. 确认 `groupPolicy` 不是 `disabled`
4. 如果用 `allowlist`，确认群 ID 在 `groupAllowFrom` 中
**获取群 ID：** 打开群聊 → 右上角菜单 → 设置，群 ID 格式为 `oc_xxx`
**获取用户 ID：** 启动 Gateway 后，给机器人发消息，查看日志中的 `open_id`，格式为 `ou_xxx`
```bash
openclaw logs --follow
```
### ❌ Gateway 启动失败
1. 检查端口是否被占用：
```bash
lsof -i :18789
```
2. 检查配置文件 JSON 语法是否合法
3. 运行诊断修复：
```bash
openclaw doctor --fix
```
### ❌ `openclaw` 命令找不到
通常是 PATH 问题，参考 **3.3 PATH 问题排查**。
---
## 十三、高级功能
### 多用户独立代理（公开服务场景）
为每个飞书用户自动创建独立的 AI 助理实例，各自拥有独立的工作空间、记忆和对话历史：
```json
{
"channels": {
"feishu": {
"dmPolicy": "open",
"allowFrom": ["*"],
"dynamicAgentCreation": {
"enabled": true,
"workspaceTemplate": "~/.openclaw/workspace-{agentId}",
"agentDirTemplate": "~/.openclaw/agents/{agentId}/agent"
}
}
},
"session": {
"dmScope": "main"
}
}
```
### 流式回复
开启后机器人会实时更新消息内容（飞书卡片形式），而非等全部生成完毕才发送：
```json
{
"channels": {
"feishu": {
"streaming": true
}
}
}
```
### 多飞书账号
```json
{
"channels": {
"feishu": {
"defaultAccount": "main",
"accounts": {
"main": {
"appId": "cli_xxx",
"appSecret": "***",
"name": "主机器人"
},
"backup": {
"appId": "cli_yyy",
"appSecret": "***",
"name": "备用机器人",
"enabled": false
}
}
}
}
}
```
---
## 参考链接
- OpenClaw 官网：[https://openclaw.ai](https://openclaw.ai)
- OpenClaw 文档：[https://docs.openclaw.ai](https://docs.openclaw.ai)
- OpenClaw GitHub：[https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)
- 智谱开放平台：[https://open.bigmodel.cn](https://open.bigmodel.cn)
- 飞书开放平台：[https://open.feishu.cn](https://open.feishu.cn)
