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 install 24
  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

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

QuickStart 模式（推荐新手）：

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

3.2 检查网关状态

openclaw gateway status

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

3.3 打开控制面板

openclaw dashboard

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

🤖 四、飞书机器人配置

4.1 创建飞书应用

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

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 启用机器人能力

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

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

4.5 配置事件订阅

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

进入 「事件订阅」：

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

4.6 发布应用

🔌 五、连接 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 在飞书中测试

6.2 常见问题排查

🐛 十、详细故障排查指南

10.1 OpenClaw 安装问题

问题：安装命令执行失败

现象：

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

解决方案：

问题：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 install 24
nvm use 24

# 验证
node –version # 应显示 v24.x.x

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

现象：

EACCES: permission denied

解决方案：

# 方法1：使用 sudo
sudo npm install -g openclaw@latest

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

10.2 网关启动问题

问题：网关无法启动

排查步骤：

# 1. 查看详细日志
openclaw logs –follow

# 2. 检查端口占用
lsof -i :18789 # macOS/Linux
netstat -ano | findstr :18789 # Windows

# 3. 如果端口被占用，更换端口
openclaw gateway –port 18888

问题：守护进程安装失败

现象：

Failed to install daemon

解决方案：

# macOS：检查 LaunchAgents 目录权限
ls -la ~/Library/LaunchAgents/

# Linux：检查 systemd 用户服务
systemctl –user status openclaw

# 手动启动（不使用守护进程）
openclaw gateway –port 18789

10.3 飞书连接问题

问题：飞书连接失败

排查清单：

问题：App ID 或 App Secret 错误

现象：

Feishu API error: invalid app_id

解决方案：

问题：权限不足

现象：

Feishu API error: permission denied

解决方案：

问题：事件订阅失败

现象：

Failed to establish WebSocket connection

解决方案：

10.4 机器人不回复问题

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

排查流程：

# 1. 实时查看日志
openclaw logs –follow

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

常见问题：

问题：AI 模型配置错误

检查步骤：

# 1. 查看当前模型配置
openclaw config show | grep -A 5 "providers"

# 2. 测试模型连接
openclaw providers test

# 3. 重新配置模型
openclaw configure –section providers

10.5 网络与防火墙问题

问题：无法访问飞书 API

测试命令：

# 测试网络连通性
curl -I https://open.feishu.cn

# 测试 DNS 解析
nslookup open.feishu.cn

# 如果使用代理
export HTTPS_PROXY=http://your-proxy:port
openclaw gateway restart

问题：本地防火墙拦截

解决方案：

Windows：

macOS：

# 检查防火墙状态
sudo /usr/libexec/ApplicationFirewall/socketfilterfw –getglobalstate

# 如果开启，添加例外
sudo /usr/libexec/ApplicationFirewall/socketfilterfw –add $(which node)

Linux：

# 检查防火墙状态
sudo ufw status

# 允许端口
sudo ufw allow 18789/tcp

10.6 日志分析与调试

查看详细日志

# 实时跟踪日志
openclaw logs –follow

# 查看最近 100 行
openclaw logs –tail 100

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

# 过滤飞书相关日志
openclaw logs –follow | grep -i feishu

开启调试模式

# 设置环境变量
export DEBUG=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 获取帮助

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

🛠️ 十一、进阶配置

7.1 环境变量配置

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

export FEISHU_APP_ID="cli_xxxxxxxxxxxx"
export FEISHU_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"
}
}
}
}
}

🔒 十二、安全建议

📚 十三、常用命令速查

# 查看网关状态
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助手 #飞书机器人 #本地部署 #智能客服