OpenClaw 本地部署完全指南：从零开始搭建你的 AI 助手（飞书接入实战）

OpenClaw 本地部署完全指南：从零开始搭建你的 AI 助手（飞书接入实战）

📌 前言

OpenClaw 是一个自托管的 AI 网关，可以将 WhatsApp、Telegram、Discord、飞书等聊天应用连接到你的 AI 助手。本文将手把手教你如何在本地完整部署 OpenClaw，并以**飞书（Feishu/Lark）**为例实现消息互通。

你将获得：

• ✅ 完全本地运行的 AI 助手网关
• ✅ 飞书机器人实时对话能力
• ✅ 支持文本、图片、文件的多媒体交互
• ✅ 数据完全自主可控

🚀 一、环境准备

1.1 系统要求

1.2 检查 Node.js 版本

node--version

如果版本过低，请先升级：

• Windows: 从 nodejs.org 下载安装包

macOS/Linux: 使用 nvm 管理

nvm install24 nvm use 24

📦 二、安装 OpenClaw

2.1 一键安装（推荐）

macOS / Linux:

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

Windows (PowerShell):

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

2.2 验证安装

openclaw --version

看到版本号即表示安装成功！

⚙️ 三、初始化配置

3.1 运行配置向导

openclaw onboard --install-daemon 

向导会引导你完成以下配置：

1. 模型提供商 - 选择 AI 模型（OpenAI、Anthropic、Kimi 等）
2. 认证方式 - API Key 或 OAuth
3. 工作空间 - 默认 ~/.openclaw/workspace
4. 网关设置 - 端口（默认 18789）、认证模式
5. 守护进程 - 自动启动服务

QuickStart 模式（推荐新手）：

• 本地网关（loopback）
• 自动生成的 Token 认证
• 端口 18789
• 默认工具策略

3.2 检查网关状态

openclaw gateway status 

如果显示 running，说明网关已启动！

3.3 打开控制面板

openclaw dashboard 

浏览器会自动打开 http://127.0.0.1:18789/，你可以在这里直接和 AI 对话（无需配置飞书即可测试）。

🤖 四、飞书机器人配置

4.1 创建飞书应用

1. 访问 飞书开放平台 并登录
   • 国际版用户请访问 Lark Open Platform
2. 点击 「创建企业自建应用」
3. 填写应用信息：
   • 应用名称：如 “AI 助手”
   • 应用描述：如 “智能问答机器人”
   • 上传应用图标（可选）

📍 操作位置：飞书开放平台 → 创建企业自建应用 → 填写基本信息

4.2 获取凭证

进入 「凭证与基础信息」，复制：

• App ID（格式：cli_xxx）
• App Secret

⚠️ 重要： App Secret 请妥善保管，不要泄露！

📍 操作位置：飞书开放平台 → 你的应用 → 凭证与基础信息 → 查看 App ID 和 App Secret

4.3 配置权限

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

{"scopes":{"tenant":["im:message","im:message:readonly","im:message:send_as_bot","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:chat.members:bot_access","im:chat.access_event.bot_p2p_chat:read","im:resource","contact:user.employee_id:readonly"],"user":["im:chat.access_event.bot_p2p_chat:read"]}}

📍 操作位置：飞书开放平台 → 你的应用 → 权限管理 → 批量导入 → 粘贴上述 JSON

4.4 启用机器人能力

进入 「应用能力」→「机器人」：

1. 开启机器人能力
2. 设置机器人名称（如 “小助手”）

📍 操作位置：飞书开放平台 → 你的应用 → 应用能力 → 机器人 → 启用

4.5 配置事件订阅

⚠️ 关键步骤： 确保 OpenClaw 网关已运行！

进入 「事件订阅」：

1. 选择 「使用长连接接收事件」（WebSocket 模式）
2. 添加事件：im.message.receive_v1

📍 操作位置：飞书开放平台 → 你的应用 → 事件订阅 → 使用长连接接收事件 → 添加事件

4.6 发布应用

1. 进入 「版本管理与发布」
2. 创建版本并提交审核
3. 等待管理员审批（企业应用通常自动通过）

🔌 五、连接 OpenClaw 与飞书

5.1 添加飞书频道

运行以下命令：

openclaw channels add

选择 Feishu，然后输入：

• App ID: cli_xxxxxxxxxxxx
• App Secret: xxxxxxxxxxxxxxxx

5.2 配置文件方式（可选）

你也可以直接编辑配置文件 ~/.openclaw/openclaw.json：

{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxxxxx","appSecret":"your-app-secret-here","botName":"AI助手"}}}}}

5.3 国际版 Lark 配置

如果你使用国际版 Lark，需要额外指定 domain：

{"channels":{"feishu":{"enabled":true,"domain":"lark","accounts":{"main":{"appId":"cli_xxxxxxxxxxxx","appSecret":"your-app-secret-here"}}}}}

5.4 重启网关

openclaw gateway restart 

5.5 查看日志

openclaw logs --follow

看到飞书连接成功的日志即表示配置完成！

✅ 六、测试与验证

6.1 在飞书中测试

1. 打开飞书，搜索你的机器人名称
2. 进入私聊或添加到群聊
3. 发送消息：“你好”
4. 机器人应该立即回复！

6.2 常见问题排查

🐛 十、详细故障排查指南

10.1 OpenClaw 安装问题

问题：安装命令执行失败

现象：

curl: (6) Could not resolve host: openclaw.ai 

解决方案：

1. 检查网络连接
2. 尝试使用代理或更换网络

手动安装：

npminstall-g openclaw@latest 

问题：Node.js 版本不兼容

现象：

Error: Node.js version 18.x is not supported 

解决方案：

# 安装 nvm（如果还没有）curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh |bash# 安装 Node 24 nvm install24 nvm use 24# 验证node--version# 应显示 v24.x.x

问题：权限不足（Linux/macOS）

现象：

EACCES: permission denied 

解决方案：

# 方法1：使用 sudosudonpminstall-g openclaw@latest # 方法2：更改 npm 全局目录mkdir ~/.npm-global npm config set prefix '~/.npm-global'echo'export PATH=~/.npm-global/bin:$PATH'>> ~/.bashrc source ~/.bashrc npminstall-g openclaw@latest 

10.2 网关启动问题

问题：网关无法启动

排查步骤：

# 1. 查看详细日志 openclaw logs --follow# 2. 检查端口占用lsof-i :18789 # macOS/Linuxnetstat-ano| findstr :18789 # Windows# 3. 如果端口被占用，更换端口 openclaw gateway --port18888

问题：守护进程安装失败

现象：

Failed to install daemon 

解决方案：

# macOS：检查 LaunchAgents 目录权限ls-la ~/Library/LaunchAgents/ # Linux：检查 systemd 用户服务 systemctl --user status openclaw # 手动启动（不使用守护进程） openclaw gateway --port18789

10.3 飞书连接问题

问题：飞书连接失败

排查清单：

检查日志

openclaw logs --follow|grep-i feishu 

验证配置

openclaw config show # 确认 channels.feishu 部分已启用

检查网关状态

openclaw gateway status # 应显示：Gateway is running

问题：App ID 或 App Secret 错误

现象：

Feishu API error: invalid app_id 

解决方案：

1. 重新复制 App ID 和 App Secret（注意空格）
2. 确认使用的是正确的应用

检查配置文件格式：

{"channels":{"feishu":{"enabled":true,"accounts":{"main":{"appId":"cli_xxxxxxxxxxxx",// 注意大小写"appSecret":"xxxxxxxxxxxx"// 确保完整}}}}}

问题：权限不足

现象：

Feishu API error: permission denied 

解决方案：

1. 进入飞书开放平台 → 你的应用 → 权限管理
2. 确认已添加以下必要权限：
   • im:message
   • im:message:readonly
   • im:message:send_as_bot
   • im:message.p2p_msg:readonly
3. 点击 「申请权限」 并等待审批

问题：事件订阅失败

现象：

Failed to establish WebSocket connection 

解决方案：

1. 确保网关已启动：openclaw gateway status
2. 检查防火墙设置
3. 检查飞书应用是否已发布（版本管理与发布）

尝试重新添加频道：

openclaw channels remove feishu openclaw channels add

10.4 机器人不回复问题

问题：飞书发送消息无响应

排查流程：

# 1. 实时查看日志 openclaw logs --follow# 2. 在飞书发送测试消息，观察日志输出# 正常情况下应看到：# [Feishu] Received message: xxx# [Agent] Processing message...# [Feishu] Sending reply: xxx

常见问题：

问题：AI 模型配置错误

检查步骤：

# 1. 查看当前模型配置 openclaw config show |grep-A5"providers"# 2. 测试模型连接 openclaw providers test# 3. 重新配置模型 openclaw configure --section providers 

10.5 网络与防火墙问题

问题：无法访问飞书 API

测试命令：

# 测试网络连通性curl-I https://open.feishu.cn # 测试 DNS 解析nslookup open.feishu.cn # 如果使用代理exportHTTPS_PROXY=http://your-proxy:port openclaw gateway restart 

问题：本地防火墙拦截

解决方案：

Windows：

1. 打开「Windows 安全中心」→「防火墙和网络保护」
2. 点击「允许应用通过防火墙」
3. 添加 Node.js 和 OpenClaw

macOS：

# 检查防火墙状态sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate# 如果开启，添加例外sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add$(whichnode)

Linux：

# 检查防火墙状态sudo ufw status # 允许端口sudo ufw allow 18789/tcp 

10.6 日志分析与调试

查看详细日志

# 实时跟踪日志 openclaw logs --follow# 查看最近 100 行 openclaw logs --tail100# 查看特定时间段的日志 openclaw logs --since"2026-03-14 10:00:00"--until"2026-03-14 12:00:00"# 过滤飞书相关日志 openclaw logs --follow|grep-i feishu 

开启调试模式

# 设置环境变量exportDEBUG=openclaw:* # 重新启动网关 openclaw gateway restart # 现在日志会显示更多调试信息

10.7 重置与重新配置

完全重置 OpenClaw

⚠️ 警告：这将删除所有配置和会话！

# 停止网关 openclaw gateway stop # 重置配置 openclaw onboard --reset# 或者完全重置（包括工作空间） openclaw onboard --reset --reset-scope full 

仅重置飞书频道

# 删除飞书配置 openclaw channels remove feishu # 重新添加 openclaw channels add

10.8 获取帮助

如果以上方法都无法解决问题：

1. 查看官方文档
   • OpenClaw 文档
   • 飞书开放平台文档
2. 社区求助
   • GitHub Issues
   • Discord 社区
3. 提交 Issue 时提供：
   • OpenClaw 版本号
   • 操作系统和版本
   • Node.js 版本
   • 完整的错误日志（脱敏后）
   • 复现步骤

收集诊断信息

# 生成诊断报告 openclaw doctor # 查看版本信息 openclaw --version# 查看系统信息 openclaw status 

🛠️ 十一、进阶配置

7.1 环境变量配置

你也可以通过环境变量配置飞书：

exportFEISHU_APP_ID="cli_xxxxxxxxxxxx"exportFEISHU_APP_SECRET="your-app-secret-here"

7.2 多账号配置

支持配置多个飞书账号：

{"channels":{"feishu":{"enabled":true,"accounts":{"work":{"appId":"cli_work_account","appSecret":"secret1"},"personal":{"appId":"cli_personal_account","appSecret":"secret2"}}}}}

7.3 Webhook 模式（高级）

如果需要使用 Webhook 而非 WebSocket：

{"channels":{"feishu":{"enabled":true,"connectionMode":"webhook","verificationToken":"your-verification-token","encryptKey":"your-encrypt-key","accounts":{"main":{"appId":"cli_xxxxxxxxxxxx","appSecret":"your-app-secret-here"}}}}}

🔒 十二、安全建议

1. 保护凭证：不要将 App Secret 提交到代码仓库
2. 使用环境变量：生产环境建议用环境变量存储敏感信息
3. 限制权限：只授予必要的权限
4. 定期检查日志：使用 openclaw logs 监控异常
5. 启用配对模式：私聊默认需要配对确认，防止未授权访问

📚 十三、常用命令速查

# 查看网关状态 openclaw gateway status # 启动网关 openclaw gateway start # 停止网关 openclaw gateway stop # 重启网关 openclaw gateway restart # 查看日志 openclaw logs --follow# 打开控制面板 openclaw dashboard # 重新配置 openclaw configure # 添加频道 openclaw channels add# 查看配置 openclaw config show 

🎯 十四、总结

恭喜你！现在你已经拥有了一个完全本地部署的 AI 助手，可以通过飞书随时随地与它对话。

OpenClaw 的优势：

• 🏠 私有化部署 - 数据完全自主可控
• 🔌 多平台支持 - 飞书、微信、Telegram、Discord 等
• 🛠️ 扩展性强 - 支持自定义技能和工具
• 💬 多媒体交互 - 支持文本、图片、文件等

下一步探索：

• 接入更多聊天渠道（Telegram、Discord 等）
• 配置自定义技能和工具
• 设置定时任务和自动化工作流

📖 十五、参考链接

• OpenClaw 官方文档
• 飞书开放平台
• Lark 开放平台
• GitHub 仓库

💡 有问题？ 欢迎在评论区留言交流！如果觉得有帮助，别忘了点赞收藏～

#OpenClaw #AI助手 #飞书机器人 #本地部署 #智能客服