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

本地部署全流程指南，祝你轻松拿下openclaw本地部署

輕華

1068人浏览 · 2026-03-14 21:01:49

輕華 · 2026-03-14 21:01:49 发布

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

📌 前言

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

你将获得：

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

🚀 一、环境准备

1.1 系统要求

项目	要求
操作系统	Windows 10/11 (WSL2)、macOS 12+、Linux
Node.js	Node 24（推荐）或 Node 22 LTS (22.16+)
内存	至少 4GB RAM
网络	可访问飞书开放平台

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

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

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

QuickStart 模式（推荐新手）：

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

3.2 检查网关状态

openclaw gateway status

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

3.3 打开控制面板

openclaw dashboard

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

🤖 四、飞书机器人配置

4.1 创建飞书应用

访问飞书开放平台并登录
- 国际版用户请访问 Lark Open Platform
点击 「创建企业自建应用」
填写应用信息：
- 应用名称：如 “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 启用机器人能力

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

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

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

4.5 配置事件订阅

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

进入 「事件订阅」：

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

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

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 常见问题排查

问题	解决方案
机器人不回复	检查网关状态 `openclaw gateway status`
连接失败	确认 App ID 和 App Secret 正确
权限错误	检查飞书应用权限是否全部授权
事件未触发	确认事件订阅中添加了 `im.message.receive_v1`

🐛 十、详细故障排查指南

10.1 OpenClaw 安装问题

问题：安装命令执行失败

现象：

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

解决方案：

检查网络连接
尝试使用代理或更换网络
手动安装：
```
npm install -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 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 飞书连接问题

问题：飞书连接失败

排查清单：

检查网关状态

openclaw gateway status
# 应显示：Gateway is running

验证配置

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

检查日志

openclaw logs --follow | grep -i feishu

问题：App ID 或 App Secret 错误

现象：

Feishu API error: invalid app_id

解决方案：

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

检查配置文件格式：

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

问题：权限不足

现象：

Feishu API error: permission denied

解决方案：

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

问题：事件订阅失败

现象：

Failed to establish WebSocket connection

解决方案：

确保网关已启动：openclaw gateway status
检查防火墙设置

尝试重新添加频道：

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 模型配置错误	检查 API Key 和模型设置
回复超时	网络或模型问题	检查网络连接，更换模型
部分消息不回复	消息类型不支持	目前仅支持文本消息

问题：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：

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

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 获取帮助

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

查看官方文档
- OpenClaw 文档
- 飞书开放平台文档

收集诊断信息

# 生成诊断报告
openclaw doctor

# 查看版本信息
openclaw --version

# 查看系统信息
openclaw status

社区求助
- GitHub Issues
- Discord 社区
提交 Issue 时提供：
- OpenClaw 版本号
- 操作系统和版本
- Node.js 版本
- 完整的错误日志（脱敏后）
- 复现步骤

🛠️ 十一、进阶配置

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"
        }
      }
    }
  }
}

🔒 十二、安全建议

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

📚 十三、常用命令速查

# 查看网关状态
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