OpenClaw 多飞书机器人完整配置教程（Docker 部署版）

低空闲话与AI杂谈
0 阅读10分钟

从单 Agent 到多 Agent，实现一个网关管理多个独立飞书机器人

一、教程概述

1.1 适用场景

  • 已有 OpenClaw Docker 部署环境
  • 需要多个飞书机器人，每个机器人独立工作
  • 每个机器人绑定不同的 Agent，使用不同的 AI 模型
  • 实现业务隔离（总控、公众号、小说、酒店、校园等）

1.2 最终架构

┌─────────────────────────────────────────────────────────────────┐
│                        飞书用户                                  │
│    ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐     │
│    │ 小智   │ │ 公众号 │ │ 小说   │ │ 酒店   │ │ 校园   │     │
│    │ 机器人 │ │ 机器人 │ │ 机器人 │ │ 机器人 │ │ 机器人 │     │
│    └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘     │
└────────┼──────────┼──────────┼──────────┼──────────┼──────────┘
         │          │          │          │          │
         ▼          ▼          ▼          ▼          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                             │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    Bindings（路由）                       │   │
│  │   account-xiaozhi  ──→  main Agent                      │   │
│  │   account-wechat   ──→  wechat-public Agent             │   │
│  │   account-novel    ──→  novel Agent                     │   │
│  │   account-hotel    ──→  hotel Agent                     │   │
│  │   account-xiaoyuan ──→  xiaoyuan Agent                  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

二、前置准备

2.1 已有环境

  • OpenClaw 已通过 Docker 部署并正常运行
  • 已有至少一个飞书机器人（小智）
  • 了解基本的 Docker 命令

2.2 飞书机器人创建与配置

在开始配置 OpenClaw 之前，需要先在飞书开放平台创建并配置机器人应用。

具体方法：参见《OpenClaw 接入飞书机器人完整教程（Docker 部署版）》的 “一、飞书开放平台配置” 章节。

简要步骤：

  1. 登录飞书开放平台，创建企业自建应用
  2. 添加机器人能力
  3. 获取 App ID 和 App Secret
  4. 配置权限（im:message、im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:message:send_as_bot 等）
  5. 配置事件订阅，选择「长连接接收事件」，添加 im.message.receive_v1 事件
  6. 发布应用版本

⚠️ 注意：每个飞书机器人需要单独创建应用，获取独立的 App ID 和 App Secret。

2.3 ⚠️ 重要风险提示：训练记忆可能丢失

风险说明
训练记忆丢失从单 Agent 升级到多 Agent 时，原有 Agent（main）的训练记忆可能无法保留
原因添加 bindings 后，路由规则变化可能导致会话 ID 重置

⚠️ 真实经历：

本次部署从单 Agent 升级到多 Agent 时，虽然提前备份了数据，但由于操作过程中的配置变更，原有训练数据未能成功恢复。这是一个惨痛的教训。

⚠️ 重要建议：

  1. 如果原有 Agent 已经有重要的训练数据，请谨慎操作，评估是否值得冒险升级。
  2. 强烈建议：从一开始部署 OpenClaw 时，就按本教程配置成多 Agent 结构。 这样后续增加新的 Agent 时，不会影响已训练过的 Agent 数据，每个 Agent 的会话独立存储，互不干扰。
# 备份命令（建议升级前执行）
cp -r /opt/openclaw /opt/openclaw.backup.$(date +%Y%m%d_%H%M%S)
cp -r /opt/openclaw/config/agents/main/sessions /opt/openclaw/backup_sessions_$(date +%Y%m%d_%H%M%S)

2.4 ⚠️ 配置修改方式的大坑（非常重要）

OpenClaw 的配置有两种修改方式，优先级不同，这是一个排查了很久才发现的坑：

方式优先级持久化
openclaw config set 命令高写入内部存储，覆盖文件配置
手动编辑 openclaw.json低仅文件修改

真实踩坑经历：

在配置群聊策略时，第一个 Agent 使用了以下命令设置了 allowlist：

openclaw config set channels.feishu.groupPolicy allowlist

后来发现群聊不生效，想改为 open，于是手动编辑 openclaw.json 将 groupPolicy 改为 "open"。但重启后始终无效，config get 查看仍然是 allowlist。

排查过程：

  • 检查 JSON 格式 ✅ 正确
  • 检查配置文件内容 ✅ 已改为 open
  • 检查容器挂载 ✅ 正常
  • 检查飞书权限 ✅ 已开通
  • 检查日志 ✅ 无报错

最终发现： openclaw config set 命令设置的值优先级高于手动编辑的 JSON 文件。即使文件中写的是 open，运行时仍然使用 config set 设置的 allowlist。

⚠️ 经验教训：

  • 尝试过先用 config unset 删除再改文件配置，实测无效
  • 唯一有效的解决方法：用 config set 命令直接覆盖
# 唯一有效的解决方法：用 config set 直接覆盖
docker exec -it openclaw-gateway openclaw config set channels.feishu.groupPolicy open

核心原则：

要么全程用命令，要么全程改文件，不要混用！如果混用了，config set 的优先级更高，手动改文件无效。而 config unset 也未必能解决问题，最可靠的方法就是统一用 config set 命令。

三、环境变量配置

3.1 编辑 .env 文件

cd /opt/openclaw
nano .env

添加所有飞书机器人的凭证：

# 小智机器人（总控）
FEISHU_XIAOZHI_APP_ID=cli_xxx
FEISHU_XIAOZHI_APP_SECRET=xxx

# 公众号机器人
FEISHU_WECHAT_APP_ID=cli_xxx
FEISHU_WECHAT_APP_SECRET=xxx

# 小说机器人
FEISHU_NOVEL_APP_ID=cli_xxx
FEISHU_NOVEL_APP_SECRET=xxx

# 酒店机器人
FEISHU_HOTEL_APP_ID=cli_xxx
FEISHU_HOTEL_APP_SECRET=xxx

# 校园机器人
FEISHU_XIAOYUAN_APP_ID=cli_xxx
FEISHU_XIAOYUAN_APP_SECRET=xxx

3.2 修改 docker-compose.yml

nano docker-compose.yml

在 environment: 部分添加：

environment:
  - NODE_ENV=production
  - LOG_LEVEL=info
  - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_TOKEN}
  - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY}
  - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
  - VOLCANO_ENGINE_API_KEY=${VOLCANO_ENGINE_API_KEY}
  - FEISHU_XIAOZHI_APP_ID=${FEISHU_XIAOZHI_APP_ID}
  - FEISHU_XIAOZHI_APP_SECRET=${FEISHU_XIAOZHI_APP_SECRET}
  - FEISHU_WECHAT_APP_ID=${FEISHU_WECHAT_APP_ID}
  - FEISHU_WECHAT_APP_SECRET=${FEISHU_WECHAT_APP_SECRET}
  - FEISHU_NOVEL_APP_ID=${FEISHU_NOVEL_APP_ID}
  - FEISHU_NOVEL_APP_SECRET=${FEISHU_NOVEL_APP_SECRET}
  - FEISHU_HOTEL_APP_ID=${FEISHU_HOTEL_APP_ID}
  - FEISHU_HOTEL_APP_SECRET=${FEISHU_HOTEL_APP_SECRET}
  - FEISHU_XIAOYUAN_APP_ID=${FEISHU_XIAOYUAN_APP_ID}
  - FEISHU_XIAOYUAN_APP_SECRET=${FEISHU_XIAOYUAN_APP_SECRET}

四、创建 Agent

每个飞书机器人对应一个独立的 Agent。

# 进入容器
docker exec -it openclaw-gateway sh

# 创建公众号助手
openclaw agents add wechat-public

# 创建小说助手
openclaw agents add novel

# 创建酒店助手
openclaw agents add hotel

# 创建校园助手
openclaw agents add xiaoyuan

# 退出容器
exit

注意：创建 Agent 时遇到 Configure chat channels now? 提示，选择 No（渠道配置稍后通过配置文件统一管理）。

五、配置文件

5.1 备份当前配置

cd /opt/openclaw
cp config/openclaw.json config/openclaw.json.bak

5.2 完整配置文件

nano config/openclaw.json

写入以下内容：

{
  "gateway": {
    "bind": "lan",
    "port": 18789,
    "auth": {
      "mode": "token"
    },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "http://localhost:37406",
        "http://127.0.0.1:37406"
      ]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    },
    "list": [
      {
        "id": "main"
      },
      {
        "id": "wechat-public",
        "name": "wechat-public",
        "workspace": "/home/node/.openclaw/workspace-wechat-public",
        "agentDir": "/home/node/.openclaw/agents/wechat-public/agent",
        "model": {
          "primary": "bailian/qwen-plus"
        }
      },
      {
        "id": "novel",
        "name": "novel",
        "workspace": "/home/node/.openclaw/workspace-novel",
        "agentDir": "/home/node/.openclaw/agents/novel/agent",
        "model": {
          "primary": "bailian/qwen-plus"
        }
      },
      {
        "id": "hotel",
        "name": "hotel",
        "workspace": "/home/node/.openclaw/workspace-hotel",
        "agentDir": "/home/node/.openclaw/agents/hotel/agent",
        "model": {
          "primary": "bailian/qwen-plus"
        }
      },
      {
        "id": "xiaoyuan",
        "name": "xiaoyuan",
        "workspace": "/home/node/.openclaw/workspace-xiaoyuan",
        "agentDir": "/home/node/.openclaw/agents/xiaoyuan/agent",
        "model": {
          "primary": "bailian/qwen-plus"
        }
      }
    ]
  },
  "models": {
    "providers": {
      "bailian": {
        "api": "openai-completions",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "${DASHSCOPE_API_KEY}",
        "models": [
          {
            "id": "qwen-plus",
            "name": "通义千问 Plus"
          }
        ]
      },
      "deepseek": {
        "api": "openai-completions",
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "${DEEPSEEK_API_KEY}",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat"
          }
        ]
      },
      "volcengine": {
        "api": "openai-completions",
        "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKey": "${VOLCANO_ENGINE_API_KEY}",
        "models": [
          {
            "id": "doubao-seed-2-0-pro-260215",
            "name": "豆包 Seed 2.0 pro"
          }
        ]
      }
    },
    "mode": "merge"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "connectionMode": "websocket",
      "requireMention": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "accounts": {
        "account-xiaozhi": {
          "appId": "${FEISHU_XIAOZHI_APP_ID}",
          "appSecret": "${FEISHU_XIAOZHI_APP_SECRET}"
        },
        "account-wechat": {
          "appId": "${FEISHU_WECHAT_APP_ID}",
          "appSecret": "${FEISHU_WECHAT_APP_SECRET}"
        },
        "account-novel": {
          "appId": "${FEISHU_NOVEL_APP_ID}",
          "appSecret": "${FEISHU_NOVEL_APP_SECRET}"
        },
        "account-hotel": {
          "appId": "${FEISHU_HOTEL_APP_ID}",
          "appSecret": "${FEISHU_HOTEL_APP_SECRET}"
        },
        "account-xiaoyuan": {
          "appId": "${FEISHU_XIAOYUAN_APP_ID}",
          "appSecret": "${FEISHU_XIAOYUAN_APP_SECRET}"
        }
      },
      "defaultAccount": "account-xiaozhi"
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "accountId": "account-xiaozhi"
      }
    },
    {
      "agentId": "wechat-public",
      "match": {
        "channel": "feishu",
        "accountId": "account-wechat"
      }
    },
    {
      "agentId": "novel",
      "match": {
        "channel": "feishu",
        "accountId": "account-novel"
      }
    },
    {
      "agentId": "hotel",
      "match": {
        "channel": "feishu",
        "accountId": "account-hotel"
      }
    },
    {
      "agentId": "xiaoyuan",
      "match": {
        "channel": "feishu",
        "accountId": "account-xiaoyuan"
      }
    }
  ],
  "plugins": {
    "entries": {
      "deepseek": {
        "enabled": true
      }
    }
  },
  "meta": {
    "lastTouchedVersion": "2026.4.8",
    "lastTouchedAt": "2026-04-10T10:12:39.868Z"
  }
}

5.3 验证 JSON 格式

cat config/openclaw.json | python3 -m json.tool > /dev/null && echo "✅ 格式正确" || echo "❌ 格式错误"

六、重启与验证

6.1 重启容器

cd /opt/openclaw
docker compose restart

6.2 查看日志

docker compose logs --tail=50 | grep -i feishu

预期输出：应该看到所有账号都显示 WebSocket client started。

6.3 查看所有 Agent

docker exec -it openclaw-gateway openclaw agents list

预期输出：

main
wechat-public
novel
hotel
xiaoyuan

七、配对机器人

7.1 触发配对

在飞书中向每个机器人发送任意消息（如"你好"），机器人会回复配对码。

7.2 查看待配对请求

docker exec -it openclaw-gateway openclaw pairing list

7.3 批准配对

docker exec -it openclaw-gateway openclaw pairing approve <配对码>

对每个机器人重复此操作。

八、群聊配置（重要）

8.1 关键配置参数

参数作用推荐值
groupPolicy群聊策略"open"（允许所有群聊）
requireMention是否需要 @ 才回复true

8.2 ⚠️ 常见问题：群聊 @ 没反应

现象原因解决方法
群聊中 @ 机器人没回复消息中没有正确 @ 机器人使用飞书的 @ 功能，选择机器人名称
日志显示 did not mention bot只打了文字，没有使用 @ 功能输入 @ 符号，从列表中选择机器人
日志显示 groupPolicy: allowlist群聊策略为白名单模式改为 "open"

8.3 检查群聊策略

# 查看当前生效的 groupPolicy
docker exec -it openclaw-gateway openclaw config get channels.feishu.groupPolicy

如果输出不是 "open"，执行：

docker exec -it openclaw-gateway openclaw config set channels.feishu.groupPolicy open
cd /opt/openclaw && docker compose restart

8.4 确认 @ 方式正确

在飞书群聊中：

  • 输入 @ 符号
  • 从弹出的列表中选择机器人
  • 确保机器人名称高亮显示（通常是蓝色）

8.5 确认机器人已在群聊中

在群聊的「群设置」→「群机器人」中，确认机器人已在列表中。

九、配置管理注意事项（重要经验）

9.1 ⚠️ 配置修改方式的选择

OpenClaw 的配置有两种修改方式，优先级不同：

方式优先级持久化
openclaw config set 命令高写入内部存储，覆盖文件配置
手动编辑 openclaw.json低仅文件修改

9.2 ⚠️ 踩坑经历（必读）

问题现象：

  • 第一个 Agent 使用 openclaw config set channels.feishu.groupPolicy allowlist 设置了群聊策略
  • 后来发现群聊不生效，想改为 open
  • 手动编辑 openclaw.json 将 groupPolicy 改为 "open"
  • 重启后始终无效，config get 查看仍然是 allowlist

排查过程：

  • 检查 JSON 格式 ✅ 正确
  • 检查配置文件内容 ✅ 已改为 open
  • 检查容器挂载 ✅ 正常
  • 检查飞书权限 ✅ 已开通
  • 检查日志 ✅ 无报错

最终发现： openclaw config set 命令设置的值优先级高于手动编辑的 JSON 文件。即使文件中写的是 open，运行时仍然使用 config set 设置的 allowlist。

⚠️ 经验教训：

  • 尝试过先用 config unset 删除再改文件配置，实测无效
  • 唯一有效的解决方法：用 config set 命令直接覆盖
# 唯一有效的解决方法：用 config set 直接覆盖
docker exec -it openclaw-gateway openclaw config set channels.feishu.groupPolicy open

9.3 推荐做法

场景推荐方式
日常配置调整统一使用 config set 命令
大规模配置迁移先 docker compose down 停止服务 → 手动编辑 → docker compose up -d
配置排查用 config get 查看运行时实际生效的值

核心原则：

要么全程用命令，要么全程改文件，不要混用！如果混用了，config set 的优先级更高，手动改文件无效。而 config unset 也未必能解决问题，最可靠的方法就是统一用 config set 命令。

9.4 查看当前生效的配置

# 查看完整运行时配置
docker exec -it openclaw-gateway openclaw config get

# 查看特定配置项
docker exec -it openclaw-gateway openclaw config get channels.feishu.groupPolicy

十、最终架构总结

飞书机器人Account IDAgent ID模型用途
小智account-xiaozhimainDeepSeek日常总控
公众号account-wechatwechat-public百炼文案写作
小说account-novelnovel百炼小说创作
酒店account-hotelhotel百炼酒店咨询
校园account-xiaoyuanxiaoyuan百炼校园助手

十一、常见问题汇总

问题原因解决方法
报错 expected record, received arrayaccounts 用了数组格式改为对象格式 { "key": { ... } }
机器人收不到消息事件订阅未配置长连接飞书开放平台选择「长连接接收事件」
配对码失效有效期约 5-10 分钟重新发送消息获取新码
原有训练记忆丢失添加 bindings 后路由变化升级前备份，升级后重新训练。建议一开始就配置成多 Agent 结构
Agent 找不到未执行 openclaw agents add先创建 Agent 再修改配置
群聊 @ 没反应没有正确 @ 机器人使用 @ 功能，从列表中选择机器人
群聊 @ 没反应groupPolicy 不是 open执行 config set channels.feishu.groupPolicy open
配置修改后不生效config set 优先级更高统一使用 config set 命令
手动改 JSON 无效config set 覆盖了文件配置用 config set 直接覆盖（config unset 实测无效）

完成以上配置后，你就可以在飞书中与多个独立的 AI 机器人对话了！ 🚀

avatar
文章
阅读
粉丝