CentOS 9 部署 OpenClaw 并接入飞书：完整实践指南

最近在折腾个人 AI 助理，想把 OpenClaw 跑在一台 CentOS 9 服务器上，再接入飞书，这样在手机上和电脑上都能随时跟它对话。踩了不少坑，也把整个流程跑通了。这篇文章就完整记录一下我的部署过程和接入飞书的步骤，希望能帮到正在做类似事情的朋友。

OpenClaw 是一个开源的 AI 助理框架，它能对接多个消息平台，让 AI 通过聊天窗口完成各种任务——查资料、写代码、调接口、操作文件，甚至定时执行脚本。飞书作为企业协作工具，机器人接口非常完善，把 OpenClaw 接进去之后，就等于给团队或自己配了一个 7x24 小时在线的 AI 助手。

这篇文章不会讲太多虚的，直接进入正题。

1. 部署前的方案选型与整体思路

1.1 先搞清楚 OpenClaw 是什么，再动手

我第一次看到 OpenClaw 这个名字的时候，第一反应是：这又是哪个 AI 项目的套壳？但实际用下来发现，它远比我想象的复杂，也远比我想象的实用。

OpenClaw 的核心定位是个人 AI 助理网关。它像是一个中转站，把各种 AI 能力（比如大语言模型的对话、工具调用、代码执行等）封装起来，然后通过不同的适配器连接到各种聊天平台。比如官方支持的平台有微信、Telegram、Discord，当然也包括飞书。

它和普通的聊天机器人最大的区别在于：OpenClaw 能主动执行任务。你可以让它定时去抓取某个网站的数据，可以让它调用 API 完成某个操作，甚至可以让它写一段代码然后直接运行。这些能力是通过插件系统实现的。

所以，如果你只是需要一个简单的问答机器人，OpenClaw 可能有点大材小用。但如果你想要一个真正能干活、能自动化的 AI 助理，那它就是非常合适的选择。

1.2 为什么我选择 CentOS 9 + Docker 方式部署

先说结论：生产环境部署，无脑选 Docker Compose 方式就好。

我在部署之前看过官方文档，OpenClaw 提供了几种安装方式：

我最终选择了 Docker 方式，原因很简单：

第一，OpenClaw 的依赖非常复杂。它依赖 Node.js 运行时、Python 环境、Redis 缓存，还会调用一些系统级依赖。如果手动逐个安装，光是把环境配好就能折腾半天。而 Docker 把这些全部打包好了。

第二，后续升级方便。Docker 镜像更新后，只需要拉取新镜像重启容器即可，不用管底层依赖。

第三，CentOS 9 自带的软件源里 Node.js 版本比较旧，如果源码安装 OpenClaw，光处理依赖版本冲突就够喝一壶的。用 Docker 能规避这些问题。

不过要注意，CentOS 9 使用 Docker 时有一个坑：系统自带的 iptables/nftables 规则和 Docker 的网络策略有冲突。 这个我后面会详细说。

1.3 整体架构与数据流向

在动手之前，先花一分钟看一下整条链路的架构，这样后面排错会清晰很多。

code复制飞书客户端 -> 飞书开放平台 -> 你的服务器（回调地址） -> OpenClaw（分析消息） -> AI模型（对话/工具调用） -> 返回结果 -> 飞书

飞书客户端发出的消息，实际上会先发到飞书开放平台，然后飞书开放平台通过事件订阅回调的方式，把消息内容 POST 到你的服务器上。OpenClaw 监听这个回调，拿到消息后解析用户意图，调用 AI 模型和工具，把结果生成出来，再通过飞书 API 发回到会话中。

所以，这里有两个关键点：

1. 服务器必须能被飞书开放平台访问到。你需要一个公网 IP，或者在服务器上配置反向代理让回调地址可达。如果服务器在内网，就需要做内网穿透或 NAT 映射。

2. 回调地址必须是 HTTPS 或有特殊配置。飞书开放平台对回调地址的安全性有要求，要么配置 HTTPS，要么在开发调试阶段使用 http 加签名验证的方式。

理解了这两点，后面的配置就不会一头雾水。

2. CentOS 9 环境初始化与 Docker 部署

2.1 系统基础配置：从新装系统到能跑 Docker

我用的是腾讯云上的 CentOS 9 Stream 镜像，2核4G内存。配置 4G 内存其实有点紧，如果任务重建议 8G，后面我会讲怎么通过 swap 来缓解。

新装系统之后，第一步肯定是更新系统包。这里有一个经验：CentOS 9 的 dnf 源在国内的速度有时不太稳定，建议先切换成国内镜像源。使用以下命令：

bash复制# 备份原始源
mv /etc/yum.repos.d/CentOS-Base.repo /etc/yum.repos.d/CentOS-Base.repo.bak
# 下载阿里云源
curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/centos-9.repo
# 清缓存并更新
dnf clean all
dnf makecache
dnf -y update

更新完成后，检查一下系统版本：

bash复制cat /etc/redhat-release

正常会显示 CentOS Stream release 9 之类的信息。

接下来配置主机名和时区，这个虽然不影响 OpenClaw 运行，但后面看日志时如果时区不对，排查问题会非常痛苦。

bash复制# 设置主机名
hostnamectl set-hostname openclaw-server

# 设置时区为上海
timedatectl set-timezone Asia/Shanghai

# 验证
date

2.2 安装 Docker CE：每一步都别省

CentOS 9 自带的软件源里其实有一个 podman-docker 包，能提供 docker 命令的兼容层，但我不推荐用。底层不是真正的 Docker Engine，遇到网络和存储问题会非常难处理。直接用 Docker 官方源安装 Docker CE 是最稳妥的。

先把 Docker 的 yum 源加进去：

bash复制# 安装 yum-utils 提供 yum-config-manager 工具
dnf -y install yum-utils

# 添加 Docker 官方源
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

这里注意，Docker 官方源在国内访问速度可能很慢。 如果安装时一直超时，可以把 /etc/yum.repos.d/docker-ce.repo 里的 download.docker.com 替换成阿里云的镜像地址：

bash复制sed -i 's|download.docker.com|mirrors.aliyun.com/docker-ce|g' /etc/yum.repos.d/docker-ce.repo

然后安装：

bash复制dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin

这里我特意把 docker-compose-plugin 也装上了，因为后面 OpenClaw 用 docker compose 启动会方便很多。在 CentOS 9 上，docker compose 是作为插件存在的，命令是 docker compose（中间有一个空格），不是老旧的 docker-compose。

启动 Docker 并设置开机自启：

bash复制systemctl enable --now docker

验证：

bash复制docker --version
docker compose version

2.3 解决 Docker 与 firewalld 的端口映射冲突

这一步是我在 CentOS 9 上踩的最大一个坑，而且是我装完 Docker 跑 Nginx 容器时发现的。现象是：容器启动成功了，但宿主机上访问不到端口，ss -tlnp 也看不到端口在监听。

查了一圈，发现问题出在 firewalld 和 Docker 的 iptables 规则冲突 上。CentOS 9 默认用的是 firewalld 管理防火墙，而 Docker 会直接操作 iptables。当 firewalld 的 DOCKER 链没有正确放行时，端口映射就不生效。

最简单的解决方案是：关闭 firewalld，改用 iptables-services 管理防火墙规则。 虽然有点粗暴，但这是最省心的做法，尤其在你对防火墙规则不是很熟悉的情况下。

bash复制# 停止并禁用 firewalld
systemctl stop firewalld
systemctl disable firewalld

# 安装 iptables-services
dnf -y install iptables-services

# 启动 iptables 并保存当前规则
systemctl enable --now iptables
iptables -F
service iptables save

注意，这里清空了所有 iptables 规则。如果你的服务器上有其他服务，记得提前备份规则。 清空之后，重新测试 Docker 端口映射就正常了。

当然，如果你对 firewalld 非常熟悉，也可以不去关闭它，但需要把 Docker 使用的网卡加到 trust 区域：

bash复制# 把 docker0 网卡和默认网段加入信任区域
firewall-cmd --permanent --zone=trusted --add-interface=docker0
firewall-cmd --permanent --zone=trusted --add-masquerade
firewall-cmd --reload

这两种方式二选一，我推荐第一种，省心。

3. OpenClaw 安装部署与配置要点

3.1 目录规划与数据持久化

在找到合适的目录之后，我先规划了一下目录结构。OpenClaw 的数据（比如密钥、配置、日志）需要持久化保存，这样容器重建后数据不丢。

我的目录规划如下：

code复制/opt/openclaw/
├── docker-compose.yml
├── .env
├── data/
│   ├── database/    # Apprise 配置
│   ├── keys/        # 密钥和签名私钥
│   ├── logs/        # 运行日志
│   └── media/       # 媒体文件
└── openclaw/        # 源码目录（如果手动克隆）

注意，如果你使用 Docker 方式部署，不需要 clone 源码。 目录里的 openclaw/ 目录主要是给源码安装的用户准备的。我一开始走了弯路，想着 clone 源码后挂载进容器，后来发现官方镜像已经把源码打进去了，只需要挂载数据目录即可。

3.2 Docker Compose 配置文件解析

OpenClaw 官方并没有直接提供 docker-compose.yml 文件，但根据社区的经验和官方文档，我整理了一份可以正常工作的配置。这里给出我的 docker-compose.yml：

yaml复制version: "3.8"

services:
  openclaw:
    image: claudeai/openclaw:latest
    container_name: openclaw
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
      - DATA_DIR=/app/data
    extra_hosts:
      - "host.docker.internal:host-gateway"

注意几点：

第一，ports 映射我用了 3000:3000，这是 OpenClaw 默认的 Web 服务端口。后面接入飞书时，回调地址就是 http://你的公网IP:3000/feishu/webhook 之类的路径。

第二，extra_hosts 配置里我把 host.docker.internal 映射到了宿主机，这是为了容器内如果需要访问宿主机的服务（比如 Redis、其他 API）能直接通过这个域名访问。

第三，restart: always 保证服务挂掉后会自动重启，这个对长期运行很重要。

写好配置文件后，在 /opt/openclaw/ 目录下执行：

bash复制docker compose up -d

第一次启动需要拉取镜像，如果建议提前在 /etc/docker/daemon.json 里配置好镜像加速器，不然可能卡在 pull 阶段。配置方法是：

bash复制mkdir -p /etc/docker
cat > /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}
EOF

# 重启 Docker 使配置生效
systemctl restart docker

3.3 验证容器运行状态

启动后等待一两分钟，让 OpenClaw 初始化。然后看一下日志：

bash复制docker logs -f openclaw

正常启动的话，日志里会看到类似下面的内容：

code复制[OpenClaw] Info: OpenClaw started successfully
[OpenClaw] Info: Web interface available at http://0.0.0.0:3000
[OpenClaw] Info: Waiting for platform connections...

看到这三行说明服务已经启动成功了。此时在浏览器里访问 http://你的公网IP:3000，应该能看到 OpenClaw 的控制台界面。

如果你的服务器有安全组或防火墙限制，记得放行 3000 端口。在腾讯云控制台的安全组规则里添加入站规则，允许 TCP 3000 端口。

这里还要提一个点：首次启动后，OpenClaw 会在 data/keys 目录下生成一对 RSA 密钥。 这对密钥用于消息签名验证，千万不要删除。如果删除了，飞书平台那边的签名校验就会失败，消息回调会一直报错。

3.4 配置管理：常用环境变量与参数说明

OpenClaw 的配置主要是通过环境变量来管理的。除了 docker-compose.yml 里的配置，还有很多可选项。下面这张表是我整理出来的常用配置项，按重要程度排序：

这里要特别提醒：在接入飞书之前，OpenClaw 并不能直接使用。 你必须先配置好至少一个 AI 模型的 API Key，否则即使飞书消息进来了，OpenClaw 也无法生成回复。

我用的是 OpenAI 兼容的 API，配置时只需要把 AI_API_KEY 和 AI_MODEL 设置为对应值。网上有很多教程只讲怎么部署，不讲怎么配置模型，结果用户部署完了发现机器人不回复，还以为是自己哪里配错了。这个坑希望大家跳过。

修改环境变量后，重启容器：

bash复制docker compose down
docker compose up -d

4. 飞书应用创建与回调配置

4.1 在飞书开放平台创建企业自建应用

这一步需要你拥有飞书管理员权限，或者能创建一个飞书开发者账号。

打开飞书开放平台（open.feishu.cn），点击「开发者后台」，然后选择「创建企业自建应用」。填写应用名称和描述，比如「AI 助理」。

这里有一个细节：应用名称会在机器人的头像和名称中显示，所以最好起一个清晰的名字。 创建完成后，你会进入应用详情页。

4.2 配置机器人能力与事件订阅

在应用详情页中，找到「添加应用能力」->「机器人」，开启机器人能力。然后进入「事件订阅」页面，这一步非常关键。

飞书的事件订阅支持两种模式：长连接和回调模式。

我选的是事件回调模式，因为在服务器上部署，公网地址是现成的。如果你是在家里或内网环境测试，可以用内网穿透工具把端口暴露到公网，但那样不稳定，只适合临时调试。

在「事件订阅」页面，需要配置请求地址和添加事件。请求地址填写：

code复制http://你的公网IP:3000/feishu/webhook

注意版本问题。 旧版 OpenClaw 的回调地址可能是 /feishu 或 /webhook/feishu，新版统一为 /feishu/webhook。如果你发现回调地址验证不通过，去看一下 OpenClaw 的日志，里面会打印出实际监听的路径。

添加事件时，需要订阅以下事件：

• im.message.receive_v1（接收消息）
• im.message.message_read_v1（消息已读，可选）
• contact.user.updated_v3（通讯录用户更新，这个通常用不到，但有的版本要求必添）

其中 im.message.receive_v1 是核心事件，必须添加。

4.3 获取凭证：App ID、App Secret、Verification Token、Encrypt Key

在「凭证与基础信息」页面，可以找到：

这里我强烈建议开启 Encrypt Key。 开启后，飞书的事件回调会使用 AES 加密，安全性会好很多。毕竟你的服务器上跑的是一个能执行代码的 AI 助理，如果回调消息被篡改，可能导致 AI 执行恶意指令。

把这四个参数记下来，下一步就要填到 OpenClaw 的配置里了。

4.4 配置签名验证：Encrypt Key 的处理逻辑

如果开启了对事件的加密，飞书在发送回调请求时，会对请求体中的 encrypt 字段做 AES 加密。OpenClaw 收到后需要先解密，才能拿到真正的消息内容。

常见的坑是：Encrypt Key 填错了，导致 OpenClaw 在解密时一直报错。 这个问题排查起来很隐蔽，因为日志只会显示 Decrypt failed 或者 Invalid request。

判断方法是：在飞书开放平台的「事件订阅」页面点击「调试」按钮，如果飞书返回的结果是 success，说明回调地址和签名验证都通过了。如果返回的是 invalid signature 或 decrypt failed，就去检查一下 Encrypt Key 是否复制正确，有没有多余的空格。

我在测试时遇到过一个诡异的问题：从飞书后台复制 Encrypt Key 时，末尾多了一个换行符，导致解密始终失败。后来在终端里用 cat -A 看了看，才发现多了一个 $（换行符）。把这个去掉之后就正常了。

5. 打通 OpenClaw 与飞书：配置落地与联调

5.1 修改 OpenClaw 配置文件

在 /opt/openclaw/docker-compose.yml 中，把刚才获取的飞书凭证添加进环境变量。

我最终的 docker-compose.yml 大概是这样的：

yaml复制version: "3.8"

services:
  openclaw:
    image: claudeai/openclaw:latest
    container_name: openclaw
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
      - DATA_DIR=/app/data
      - LOG_LEVEL=debug
      # 飞书配置
      - FEISHU_APP_ID=cli_xxxxxxx
      - FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
      - FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
      - FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxx
      # AI 模型配置
      - AI_API_KEY=sk-xxxxxxxxxxxxxxxx
      - AI_MODEL=gpt-4o-mini
    extra_hosts:
      - "host.docker.internal:host-gateway"

注意，AI_MODEL 填什么取决于你用哪家模型。 如果是 OpenAI 兼容接口，就填模型名；如果是 Claude，就填 claude-3-5-sonnet 之类的。这些信息在官方文档里都有。

修改完配置后，重启容器：

bash复制cd /opt/openclaw
docker compose down
docker compose up -d

然后看日志检查是否加载了飞书配置：

bash复制docker logs -f openclaw

如果看到类似这样的日志，说明飞书配置加载成功了：

code复制[OpenClaw] Info: Feishu adapter initialized
[OpenClaw] Info: Feishu webhook server listening at /feishu/webhook

5.2 在飞书开放平台验证回调地址

回到飞书开放平台的「事件订阅」页面，点击「验证」按钮。飞书会发送一个验证请求到你配置的回调地址，如果一切正常，页面会提示「验证通过」。

如果验证失败，怎么办？ 常见的失败原因有三个：

1. 端口不通。 在服务器上执行 curl -X POST http://localhost:3000/feishu/webhook -d '{"challenge":"123"}'，看是否能返回带 challenge 的响应。如果这个命令都失败，说明 OpenClaw 根本没有在监听 3000 端口，或者端口映射有问题。

2. Encrypt Key 不匹配。 去日志里看有没有解密失败的记录。

3. 服务器防火墙阻断了飞书 IP。 飞书开放平台的事件回调来自固定的 IP 段，如果你在服务器上配置了严格的 iptables 规则，需要放行飞书的 IP 段。

我自己遇到的最恶心的问题就是第三种。当时服务器上的 iptables 规则是之前运维留下的，默认 DROP 策略，飞书回调的 IP 段没有放行，导致回调验证一直超时。排查了好久才想起来去看 iptables 规则。

5.3 联调测试：从飞书发消息到收到 AI 回复

回调地址验证通过之后，就可以开始真正的联调测试了。

在飞书里找到你刚创建的应用，给它发一条消息，比如「你好」。正常情况下，几秒钟内你应该能收到 OpenClaw 的回复。

如果没收到回复，按照下面的顺序排查：

第一步，打开 OpenClaw 的日志实时输出：

bash复制docker logs -f openclaw

第二步，在飞书里再发一条消息，观察日志变化。

如果日志里没有任何输出，说明飞书的消息根本没有回调到 OpenClaw。这时去飞书开放平台的事件订阅页面看有没有报错记录。

如果日志里有消息接收记录但没有回复，说明消息进来了，但 AI 模型调用失败。大概率是 API Key 没配置好，或者模型名称填错了。日志里会有具体的报错信息。

如果日志显示消息已经回复但飞书里没收到，那就是 API 调用链路上的问题。检查一下 OpenClaw 是否有权限调用飞书 API 发消息，比如应用是否开通了「机器人发消息」的权限。

我这里的经验是：联调阶段一定要开 debug 日志。在 docker-compose.yml 里设置 LOG_LEVEL=debug，日志会详细到每一个 HTTP 请求、每一次 API 调用，排查问题会快很多。

6. 常见问题与排障手册

6.1 高频问题速查：部署阶段

6.2 高频问题速查：飞书接入阶段

6.3 几个容易忽略的细节

第一，SELinux。 CentOS 9 默认是开启 SELinux 的，而且状态是 Enforcing。如果你挂载了宿主机目录到容器里，SELinux 有可能会阻止容器读写这个目录。最简单的解决方式是临时关闭 SELinux 测试：

bash复制setenforce 0

如果关闭后问题消失，说明确实是 SELinux 导致的。这时不要直接把 SELinux 永久关闭（虽然我见过很多人这么做），而是给挂载目录添加正确的上下文标签：

bash复制chcon -Rt svirt_sandbox_file_t /opt/openclaw/data

或者，如果像我一样图省事，可以在 /etc/selinux/config 里把 SELINUX=enforcing 改成 disabled，然后重启。不过生产环境我建议还是保留 SELinux，学会用 chcon 或 semanage 才是正解。

第二，swap 空间。 前面提到我用的服务器是 4G 内存。如果 AI 模型在回答问题时要处理大量上下文，OpenClaw 占用的内存可能会飙到 3G 以上，此时随时可能触发 OOM 导致容器被杀掉。为了防止这种情况，我建议加 2G swap：

bash复制# 创建 2G 的 swap 文件
dd if=/dev/zero of=/swapfile bs=1M count=2048
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

# 写入 /etc/fstab 实现开机自挂载
echo '/swapfile swap swap defaults 0 0' >> /etc/fstab

加了 swap 之后，即使内存不太够，容器也不容易因为 OOM 崩溃。虽然 swap 比内存慢很多，但至少能撑住服务不挂。

第三，日志轮转。 OpenClaw 运行时间长了之后，日志文件会非常大。Docker 自带的 json-file 日志驱动默认不裁剪，需要配置一下日志轮转。在 /etc/docker/daemon.json 里加上：

json复制{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

然后重启 Docker 生效。这个配置会把每个容器日志限制在 30M 以内，防止日志把磁盘撑爆。

6.4 监控与告警的补充思路

如果你打算让 OpenClaw 长期运行，监控是必不可少的一环。我自己是在同一个服务器上跑了一个轻量的监控脚本，每 5 分钟检查一次：

bash复制#!/bin/bash
if ! docker ps | grep -q openclaw; then
    echo "$(date) - OpenClaw 容器挂掉了，正在重启..." >> /var/log/openclaw-monitor.log
    docker start openclaw
fi

这个脚本配合 cron 使用，可以保证 OpenClaw 即使意外挂掉也能快速恢复。当然，如果条件允许，接上 Prometheus + Grafana 或者 UptimeRobot 之类的监控平台会更专业一些。

7. 最后的几点心得

整个 OpenClaw + 飞书 的部署过程，说难不难，说简单也不简单。踩过一圈坑之后，我最大的感受是：部署本身只是很小的一部分，真正的难点在于把各个组件的角色搞清楚。

飞书回调、OpenClaw 的 webhook 监听、AI 模型 API 调用，这三个环节任何一个出问题都可能导致整个链路不通。建议大家在部署时，按阶段验收，不要一次性全配好再调试。先把 OpenClaw 跑起来，用浏览器访问控制台确认服务正常；再配置飞书事件订阅，确认验证通过；最后再接入 AI 模型，发消息测试。

这样每一步的报错都只有一个可能的原因，排查起来会轻松很多。

还有一个体验上的建议：OpenClaw 接入飞书后，不要一上来就让它执行高权限的命令或操作真实系统。先在测试环境让它跑通基础对话和简单的任务，确认行为符合预期之后，再循序放开权限。毕竟，AI 助理的能力越强，出问题时造成的破坏也可能越大。

希望这篇文章能帮你少踩几个坑。如果你在部署过程中遇到其他问题，欢迎在评论区留言讨论。