# 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以**管理员身份**打开 PowerShellpowershellwsl --install安装完成后重启电脑。如需将 WSL 迁移到其他盘比如 E 盘powershellwsl --shutdownwsl --manage Ubuntu --move E:\WSL\Ubuntu进入 WSLpowershellwsl -d Ubuntu---## 三、安装 OpenClaw### 3.1 一键安装在 WSL / Linux / macOS 终端中运行bashcurl -fsSL https://openclaw.ai/install.sh | bash如果想跳过引导稍后手动配置bashcurl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard### 3.2 验证安装bashopenclaw --version正常输出类似OpenClaw 2026.6.1### 3.3 PATH 问题排查如果 openclaw 命令找不到bashnpm config get prefix确保输出的路径在 PATH 中。需要的话在 ~/.bashrc 末尾添加bashexport PATH$HOME/.npm-global/bin:$PATH然后执行bashsource ~/.bashrc---## 四、配置 AI 模型智谱 GLM **获取 API 密钥** 前往 [智谱开放平台](https://open.bigmodel.cn) 注册账号 → API Keys → 创建新的 API Key。### 方式一交互式引导bashopenclaw onboard选择 zai-api-key 或 custom-api-key按提示输入密钥。### 方式二非交互式推荐bashopenclaw 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 安装为系统服务推荐开机自启bashopenclaw gateway restart --install-daemon### 5.2 前台运行调试用bashopenclaw gateway run --port 18789### 5.3 验证状态bashopenclaw gateway status正常输出关键信息Runtime: running (pid xxxx, state active, sub running)Connectivity probe: okListening: 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 接入飞书### 方式一交互式配置推荐新手bashopenclaw 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 使配置生效bashopenclaw gateway restart---## 八、配对认证仅 pairing 模式如果 dmPolicy 设为 pairing用户首次私聊机器人时会收到配对码需要在终端批准bash# 查看待批准的配对请求openclaw pairing list feishu# 批准配对openclaw pairing approve feishu 配对码---## 九、验证是否成功1. 在飞书中搜索并找到你的机器人2. 发送一条消息如「你好」3. 检查是否收到 AI 回复4. 如有问题查看日志bashopenclaw 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 status2. 查看日志openclaw logs --follow3. 确认飞书应用已发布并审批通过4. 确认事件订阅包含 im.message.receive_v15. 确认选择了「长连接」模式6. 确认所有权限已申请并审批通过### ❌ 群聊中机器人不回复1. 确认机器人已加入群聊2. 确认在群里 **了机器人**默认必须 3. 确认 groupPolicy 不是 disabled4. 如果用 allowlist确认群 ID 在 groupAllowFrom 中**获取群 ID** 打开群聊 → 右上角菜单 → 设置群 ID 格式为 oc_xxx**获取用户 ID** 启动 Gateway 后给机器人发消息查看日志中的 open_id格式为 ou_xxxbashopenclaw logs --follow### ❌ Gateway 启动失败1. 检查端口是否被占用bashlsof -i :187892. 检查配置文件 JSON 语法是否合法3. 运行诊断修复bashopenclaw 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)