openclaw接入飞书机器人

阿祥_csdn2026-03-16 16:09

接入的教程

一、前置准备

安装飞书插件：

复制代码 
npx -y @larksuite/openclaw-lark-tools install

1.1 创建飞书应用

  1. 访问 飞书开放平台
  2. 创建企业自建应用
  3. 记录应用的 App ID 和 App Secret

1.2 配置事件订阅

进入应用的「事件订阅」页面，选择 Stream 模式（WebSocket 长连接）。

1.3 添加订阅事件

事件名称 用途
im.message.receive_v1 接收消息
im.message.reaction.created_v1 表情回应（可选）

1.4 配置应用权限

在「权限管理」中添加以下权限：

权限名称 说明
im:message 获取与发送消息
im:message:send_as_bot 以应用身份发消息
im:chat 获取群组信息
im:chat:readonly 读取群组信息
contact:user.base:readonly 获取用户基础信息

1.5 发布应用版本

配置完成后，创建版本并发布应用。

二、OpenClaw 配置

2.1 配置文件位置

复制代码 
C:\Users\Administrator\.openclaw\openclaw.json

2.2 完整配置文件示例

以下是完整的 openclaw.json 配置文件，重点关注 channels 和 plugins 部分：

json 复制代码 
{
  "models": {
    "mode": "merge",
    "providers": {
      "your-provider": {
        "baseUrl": "https://your-api-endpoint/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model-id",
            "name": "your-model-name",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "your-provider/your-model-id"
      },
      "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main"
      }
    ]
  },
  "tools": {
    "profile": "full"
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "****",
      "appSecret": "****",
      "domain": "feishu",
      "connectionMode": "websocket",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "groupPolicy": "open",
      "groupAllowFrom": ["*"],
      "requireMention": true,
      "typingIndicator": true,
      "resolveSenderNames": true
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

2.3 配置参数详解

基础配置
参数 类型 必填 说明
enabled boolean 是 是否启用飞书通道。true 启用，false 禁用
appId string 是 飞书应用的 App ID，在飞书开放平台「凭证与基础信息」页面获取。格式：cli_xxxxxxxx
appSecret string 是 飞书应用的 App Secret，在飞书开放平台「凭证与基础信息」页面获取。格式：32 位字符串
domain string 否 飞书域名。取值 ："feishu"（国内版，默认）、"lark"（国际版）
connectionMode string 否 连接模式。取值 ："websocket"（默认，推荐）、"webhook"（需公网服务器）
私聊配置
参数 类型 必填 说明
dmPolicy string 否 私聊策略。取值 ："open"（开放，任何人可私聊）、"pairing"（需配对确认）、"allowlist"（白名单模式）。默认 ："pairing"
allowFrom array 否 允许私聊的用户列表。取值 ：["*"]（允许所有人）、["ou_user1", "ou_user2"]（指定用户的 open_id）。注意 ：dmPolicy: "open" 时必须包含 "*"
群聊配置
参数 类型 必填 说明
groupPolicy string 否 群聊策略。取值 ："open"（开放，任何群可用）、"allowlist"（白名单模式）、"disabled"（禁用群聊）。默认 ："allowlist"
groupAllowFrom array 否 允许的群聊列表。取值 ：["*"]（允许所有群）、["oc_group1", "oc_group2"]（指定群的 chat_id）
requireMention boolean 否 群聊是否需要 @机器人 才会响应。取值 ：true（需要 @）、false（所有消息都响应）。默认 ：true
体验优化配置
参数 类型 必填 说明
typingIndicator boolean 否 是否显示「正在输入...」状态。取值 ：true（显示）、false（不显示）。默认 ：true
resolveSenderNames boolean 否 是否解析发送者名称。取值 ：true（解析，消息中会显示发送者名字）、false（不解析）。默认 ：true
Webhook 模式专用配置
参数 类型 必填 说明
webhookHost string 是* Webhook 服务器域名，如 "example.com"。*仅 webhook 模式需要
webhookPort number 否 Webhook 服务器端口，如 443、8080
webhookPath string 否 Webhook 接收路径。默认 ："/feishu/events"
verificationToken string 是* 飞书事件订阅的验证令牌，在飞书开放平台获取。*仅 webhook 模式需要
如何获取必要信息
信息 获取方式
appId / appSecret 飞书开放平台 → 你的应用 → 凭证与基础信息
用户的 open_id 让用户给机器人发消息，查看日志中的 open_id 字段；或通过飞书 API 获取
群聊的 chat_id 将机器人加入群聊，查看日志中的 chat_id 字段；或在飞书群设置中查看
verificationToken 飞书开放平台 → 你的应用 → 事件订阅 → 验证令牌

三、启动与验证

3.1 启动 Gateway

bash 复制代码 
# 启动 OpenClaw Gateway
/c/Users/Administrator/.openclaw/gateway.cmd

3.2 验证连接成功

启动成功后会看到以下日志：

复制代码 
[feishu] starting feishu[default] (mode: websocket)
[feishu] feishu[default]: bot open_id resolved: ou_xxxxxxxx
[feishu] feishu[default]: starting WebSocket connection...

3.3 测试机器人

  • 私聊测试：在飞书中直接给机器人发送消息
  • 群聊测试：将机器人拉入群聊，@机器人 后发送消息

四、日志查看

bash 复制代码 
# 查看实时日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看完整日志
cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

使用的教程

一、私聊使用

直接在飞书中给机器人发送消息即可开始对话。

二、群聊使用

在群聊中需要 @机器人 才会触发回复（除非配置了 requireMention: false）。

三、高级配置

以下示例均为完整的 openclaw.json 配置文件，请直接替换或参考修改。

3.1 白名单模式

只允许特定用户和群聊使用机器人：

json 复制代码 
{
  "models": {
    "mode": "merge",
    "providers": {
      "your-provider": {
        "baseUrl": "https://your-api-endpoint/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model-id",
            "name": "your-model-name",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "your-provider/your-model-id" },
      "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    },
    "list": [{ "id": "main" }]
  },
  "tools": { "profile": "full" },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": { "dmScope": "per-channel-peer" },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "****",
      "appSecret": "****",
      "domain": "feishu",
      "connectionMode": "websocket",
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_user1", "ou_user2"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["oc_group1"],
      "requireMention": true,
      "typingIndicator": true,
      "resolveSenderNames": true
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "your-gateway-token" },
    "tailscale": { "mode": "off", "resetOnExit": false },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "entries": { "feishu": { "enabled": true } }
  }
}

字段说明：

  • dmPolicy: "allowlist" - 使用白名单模式限制私聊，只有 allowFrom 列表中的用户可以私聊
  • allowFrom: ["ou_user1", "ou_user2"] - 允许私聊的用户 open_id 列表。ou_user1、ou_user2 需替换为实际的用户 open_id
  • groupPolicy: "allowlist" - 使用白名单模式限制群聊，只有 groupAllowFrom 列表中的群可以触发机器人
  • groupAllowFrom: ["oc_group1"] - 允许的群聊 chat_id 列表。oc_group1 需替换为实际的群 chat_id

3.2 多账号支持

一个 OpenClaw 实例管理多个飞书机器人：

json 复制代码 
{
  "models": {
    "mode": "merge",
    "providers": {
      "your-provider": {
        "baseUrl": "https://your-api-endpoint/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model-id",
            "name": "your-model-name",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "your-provider/your-model-id" },
      "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    },
    "list": [{ "id": "main" }]
  },
  "tools": { "profile": "full" },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": { "dmScope": "per-channel-peer" },
  "channels": {
    "feishu": {
      "enabled": true,
      "defaultAccount": "bot1",
      "domain": "feishu",
      "connectionMode": "websocket",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "groupPolicy": "open",
      "groupAllowFrom": ["*"],
      "requireMention": true,
      "typingIndicator": true,
      "resolveSenderNames": true,
      "accounts": {
        "bot1": {
          "name": "客服机器人",
          "appId": "cli_xxx1",
          "appSecret": "secret1"
        },
        "bot2": {
          "name": "助手机器人",
          "appId": "cli_xxx2",
          "appSecret": "secret2"
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "your-gateway-token" },
    "tailscale": { "mode": "off", "resetOnExit": false },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "entries": { "feishu": { "enabled": true } }
  }
}

字段说明：

  • defaultAccount: "bot1" - 默认使用的机器人账号，当没有指定账号时使用此账号
  • accounts - 多个机器人账号配置对象
    • bot1 / bot2 - 自定义的账号标识符，用于区分不同机器人
    • name - 账号显示名称，方便识别，可选
    • appId - 该机器人账号的 App ID，格式：cli_xxxxxxxx
    • appSecret - 该机器人账号的 App Secret，32 位字符串

3.3 自定义群聊配置

为特定群聊设置不同的行为：

json 复制代码 
{
  "models": {
    "mode": "merge",
    "providers": {
      "your-provider": {
        "baseUrl": "https://your-api-endpoint/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model-id",
            "name": "your-model-name",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "your-provider/your-model-id" },
      "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    },
    "list": [{ "id": "main" }]
  },
  "tools": { "profile": "full" },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": { "dmScope": "per-channel-peer" },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "****",
      "appSecret": "****",
      "domain": "feishu",
      "connectionMode": "websocket",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "groupPolicy": "open",
      "groupAllowFrom": ["*"],
      "requireMention": true,
      "typingIndicator": true,
      "resolveSenderNames": true,
      "groups": {
        "oc_xxxxxxxx": {
          "enabled": true,
          "requireMention": false,
          "systemPrompt": "你是一个专业的客服助手，请用简洁专业的语言回答问题。"
        },
        "oc_yyyyyyyy": {
          "enabled": true,
          "requireMention": true,
          "systemPrompt": "你是一个技术顾问，专注于解决编程和技术问题。"
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "your-gateway-token" },
    "tailscale": { "mode": "off", "resetOnExit": false },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "entries": { "feishu": { "enabled": true } }
  }
}

字段说明：

  • groups - 按群聊 ID 进行个性化配置的对象
    • oc_xxxxxxxx / oc_yyyyyyyy - 群聊的 chat_id，需要替换为实际的群 ID
    • enabled - 是否在该群启用机器人，true 启用，false 禁用
    • requireMention - 该群是否需要 @机器人。设置为 false 可覆盖全局设置，让机器人在该群响应所有消息
    • systemPrompt - 该群使用的系统提示词，可让机器人在不同群扮演不同角色

常见问题

一、机器人无响应

  1. 检查应用是否已发布版本
  2. 检查事件订阅是否配置正确
  3. 检查权限是否已添加
  4. 查看日志文件排查错误

二、WebSocket 连接失败

  1. 检查网络是否能访问飞书服务器
  2. 确认 App ID 和 App Secret 是否正确
  3. 确认应用已启用 Stream 模式

三、群聊机器人不回复

  1. 确认机器人已加入该群
  2. 确认消息中 @了机器人
  3. 检查 requireMention 配置

四、如何切换飞书机器人对应的 openclaw

如果需要将飞书机器人切换到另一个 OpenClaw 实例：

方法一：修改配置文件

  1. 停止当前 OpenClaw Gateway
  2. 将 openclaw.json 中的飞书配置复制到新的 OpenClaw 实例
  3. 启动新的 OpenClaw Gateway

方法二：使用环境变量

bash 复制代码 
# 设置配置文件路径
export OPENCLAW_CONFIG_PATH=/path/to/new/openclaw.json

# 启动 Gateway
/c/Users/Administrator/.openclaw/gateway.cmd

注意事项

  • 同一时间只能有一个 OpenClaw 实例连接同一个飞书机器人
  • WebSocket 模式下，新连接会自动断开旧连接
  • 切换后需要等待几秒钟让飞书服务器更新连接状态

五、如果多个 openclaw 接入了同一个飞书机器人，该如何处理？

问题说明

飞书 WebSocket 模式是单连接的，同一时间只能有一个客户端保持连接。如果多个 OpenClaw 实例尝试连接同一个飞书机器人：

  • 后连接的实例会成功建立连接
  • 先连接的实例会被断开，出现连接丢失

解决方案

方案一：单实例部署（推荐）

只运行一个 OpenClaw Gateway 实例，通过配置文件管理多个机器人账号。参见上方「3.2 多账号支持」。

方案二：使用 Webhook 模式

如果需要多实例部署，可以改用 Webhook 模式。

完整配置文件示例：

json 复制代码 
{
  "models": {
    "mode": "merge",
    "providers": {
      "your-provider": {
        "baseUrl": "https://your-api-endpoint/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model-id",
            "name": "your-model-name",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "your-provider/your-model-id" },
      "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    },
    "list": [{ "id": "main" }]
  },
  "tools": { "profile": "full" },
  "messages": { "ackReactionScope": "group-mentions" },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": { "dmScope": "per-channel-peer" },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "****",
      "appSecret": "****",
      "domain": "feishu",
      "connectionMode": "webhook",
      "webhookHost": "your-domain.com",
      "webhookPort": 443,
      "webhookPath": "/feishu/events",
      "verificationToken": "your_verification_token",
      "dmPolicy": "open",
      "allowFrom": ["*"],
      "groupPolicy": "open",
      "groupAllowFrom": ["*"],
      "requireMention": true,
      "typingIndicator": true,
      "resolveSenderNames": true
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "your-gateway-token" },
    "tailscale": { "mode": "off", "resetOnExit": false },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "entries": { "feishu": { "enabled": true } }
  }
}

Webhook 模式需要：

  • 公网可访问的服务器
  • 配置 HTTPS（飞书要求）
  • 在飞书开放平台配置事件推送 URL：https://your-domain.com/feishu/events
方案三：负载均衡

使用消息队列（如 Redis、RabbitMQ）进行消息分发：

  1. 单一入口接收飞书消息
  2. 通过消息队列分发到多个处理节点
  3. 结果汇总后返回

架构建议

场景 推荐方案
单机器人、单租户 单实例 WebSocket
多机器人、单租户 单实例多账号配置
单机器人、高可用 主备切换 + WebSocket
高并发、多租户 Webhook + 负载均衡

六、相关链接

相关推荐
Jay-r2 小时前
OpenClaw养龙虾工具安全风险分析：五大隐患及防护建议引言
网络·python·安全·web安全·ai助手·openclaw
乱世刀疤3 小时前
云主机ubuntu24上安装openclaw后配置飞书通道
人工智能·openclaw
V搜xhliang02463 小时前
手术机器人导航软件
大数据·人工智能·机器学习·自然语言处理·机器人
墨10244 小时前
当 AI 助手开始管理多个项目：如何把“继续某项目”变成可联动机制
人工智能·ai·项目管理·架构设计·工程实践·openclaw
超级璐璐4 小时前
fastlivo2修改记录
机器人
小付爱coding4 小时前
openclaw源码架构深度解析【总体概况】
python·架构·openclaw
码点5 小时前
OpenClaw + 飞书 + nodejs
飞书
爱学习的小道长5 小时前
OpenClaw解决飞书 duplicate plugin id detected 问题
飞书
信道者5 小时前
俄乌战场开启“机器人战争”时代：UGV成建制投入实战
机器人
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04本地部署 OpenClaw + DeepSeek-R1 完全指南05UV安装并设置国内源06OpenClaw macOS 完整安装与本地模型配置教程（实战版）07OpenClaw Control UI安全上下文访问配置08Openclow安装保姆级教程09在 Windows 上配置 Claude Code从安装到解决网络问题10OpenClaw 飞书机器人不回复消息？3 小时踩坑总结