OpenClaw+飞书官方插件多Agent 部署指南

基于 @larksuite/openclaw-lark 官方飞书插件，实现一个飞书企业下多个机器人应用分别对接不同 AI Agent 的完整配置方案。

本文档基于 OpenClaw 2026.3.13 + openclaw-lark 2026.3.17 实际部署验证。

架构概览

飞书企业
├── 主助手 Bot (cli_xxx1)   ──→  main Agent      (DeepSeek-chat)
├── 开发助手 Bot (cli_xxx2)  ──→  developer Agent  (deepseek-chat)
├──写作助手 Bot (cli_xxx3) ──→  writer Agent     (openrouter/auto)
├──分析助手 Bot (cli_xxx4) ──→  analyst Agent    (openrouter/auto)
└── 运维助手 Bot (cli_xxx5)  ──→  ops Agent      (deepseek-chat)
                                       │
                               OpenClaw Gateway (单进程)
                               openclaw-lark 插件 (WebSocket)

核心思路：同一飞书企业下创建多个机器人应用，每个机器人在 OpenClaw 中作为一个 account，通过 bindings 路由到不同的 Agent。 每个 Agent 拥有独立的工作空间、性格文件（SOUL.md）、记忆和模型配置。

环境要求

依赖	版本要求	说明
Node.js	>= 22	推荐 v22 LTS
OpenClaw	>= 2026.2.26	多 Agent bindings 需要 >= 2026.3.13
操作系统	Linux / macOS	推荐 Linux + systemd

第一步：安装 OpenClaw

npm install -g openclawopenclaw -v# 输出: OpenClaw 2026.3.13

初始化配置：

openclaw config

按向导完成基础配置，会生成 ~/.openclaw/openclaw.json。

第二步：配置模型

DeepSeek（自有 API Key）

"models": {  "mode": "merge",  "providers": {    "deepseek": {      "baseUrl": "https://api.deepseek.com/v1",      "apiKey": "sk-your-deepseek-api-key",      "api": "openai-completions",      "models": [        { "id": "deepseek-chat", "name": "DeepSeek Chat" },        { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner" }      ]    }  }}

OpenRouter（聚合模型路由）

openclaw auth add openrouter# 按提示输入 OpenRouter API Key

配置完成后 auth.profiles 会自动生成：

"auth": {  "profiles": {    "openrouter:default": {      "provider": "openrouter",      "mode": "api_key"    }  }}

Agent 中直接使用 "model": "openrouter/auto" 即可。

第三步：飞书开放平台创建机器人

在飞书开放平台上，为每个 Agent 创建一个企业自建应用。

3.1 创建应用

每个 Agent 创建一个应用，例如：主助手、开发助手、写作助手、分析助手、运维助手。

3.2 添加机器人能力

进入应用管理页面 → 添加应用能力 → 选择 机器人。

3.3 批量导入权限

权限管理 → 批量导入，粘贴以下 JSON：

{  "scopes": {    "tenant": [      "aily:file:read",      "aily:file:write",      "application:application.app_message_stats.overview:readonly",      "application:bot.menu:write",      "cardkit:card:write",      "contact:contact.base:readonly",      "contact:user.employee_id:readonly",      "docs:document.content:read",      "event:ip_list",      "im:chat",      "im:chat.access_event.bot_p2p_chat:read",      "im:chat.members:bot_access",      "im:message",      "im:message.group_at_msg:readonly",      "im:message.group_msg",      "im:message.p2p_msg:readonly",      "im:message:readonly",      "im:message:send_as_bot",      "im:resource",      "sheets:spreadsheet",      "wiki:wiki:readonly"    ],    "user": [      "aily:file:read",      "aily:file:write",      "im:chat.access_event.bot_p2p_chat:read"    ]  }}

3.4 配置事件订阅

事件订阅 → 启用 长连接（WebSocket 模式） → 添加事件 im.message.receive_v1。

长连接模式不需要公网 IP，OpenClaw 主动连接飞书服务器，适合内网/NAT 环境。

3.5 发布应用

版本管理与发布 → 创建版本 → 提交发布。

发布后在 凭证与基础信息 页面获取 App ID（cli_xxx）和 App Secret。

每个机器人应用都要重复以上步骤。

第四步：安装飞书官方插件

openclaw plugins install @larksuite/openclaw-lark

验证安装：

openclaw status# Channels: Feishu ON OK# Plugins: Loaded: 1

第五步：配置 openclaw.json

以下为 ~/.openclaw/openclaw.json 中各核心配置段的详解。

1. 飞书频道配置

"channels": {  "feishu": {    "enabled": true,    "domain": "feishu",    "streaming": true,    // ★ 默认机器人（主助手）凭证必须放在顶层，不要放在 accounts 里    "appId": "cli_主助手的AppID",    "appSecret": "主助手的AppSecret",    "botName": "主助手",    // 私聊策略    "dmPolicy": "allowlist",    "allowFrom": ["ou_你的用户OpenID"],    // 群聊策略    "requireMention": true,    "groupPolicy": "allowlist",    "groupAllowFrom": ["oc_允许的群聊ID"],    // ★ 其他机器人放在 accounts 里    "accounts": {      "developer": {        "appId": "cli_开发助手AppID",        "appSecret": "开发助手AppSecret",        "botName": "开发助手"      },      "writer": {        "appId": "cli_写作助手AppID",        "appSecret": "写作助手AppSecret",        "botName": "写作助手"      },      "analyst": {        "appId": "cli_分析助手AppID",        "appSecret": "分析助手AppSecret",        "botName": "分析助手"      },      "ops": {        "appId": "cli_运维助手AppID",        "appSecret": "运维助手AppSecret",        "botName": "运维助手",        // 运维助手允许所有人对话        "dmPolicy": "open",        "allowFrom": ["*"]      }    },    // 群组配置    "groups": {      "*": {        "requireMention": true      },      "oc_指定群聊ID": {        "requireMention": false,        "groupPolicy": "open"      }    }  }}

关键点：

默认机器人（main）的 appId/appSecret 放在 channels.feishu顶层，这是 openclaw-lark 插件的硬性要求（源码 accounts.js 中 default 账号只从顶层读取）

其他机器人放在 accounts 下面，key 名与 Agent ID 对应

每个 account 可以独立覆盖 dmPolicy、allowFrom 等策略

doctor --fix

会建议把顶层凭证移到 accounts.default，不要执行，否则默认机器人会断连

2. 多 Agent 定义

"agents": {  "defaults": {    "compaction": { "mode": "safeguard" }  },  "list": [    {      "id": "main",      "default": true,      "name": "main",      "workspace": "/root/.openclaw/workspace",      "agentDir": "/root/.openclaw/agents/main/agent",      "model": "deepseek/deepseek-chat"    },    {      "id": "developer",      "name": "developer",      "workspace": "/root/.openclaw/workspace-developer",      "agentDir": "/root/.openclaw/agents/developer/agent",      "model": "deepseek/deepseek-chat"    },    {      "id": "writer",      "name": "writer",      "workspace": "/root/.openclaw/workspace-writer",      "agentDir": "/root/.openclaw/agents/writer/agent",      "model": "openrouter/auto"    },    {      "id": "analyst",      "name": "analyst",      "workspace": "/root/.openclaw/workspace-analyst",      "agentDir": "/root/.openclaw/agents/analyst/agent",      "model": "openrouter/auto"    },    {      "id": "ops",      "name": "运维助手",      "workspace": "/root/.openclaw/workspace-ops",      "agentDir": "/root/.openclaw/agents/ops/agent",      "model": "deepseek/deepseek-chat"    }  ]}

每个 Agent 有三个关键目录：

目录	说明
`workspace`	工作空间根目录，存放 `SOUL.md`、`USER.md`、`memory/` 等
`agentDir`	Agent 运行目录，存放模型配置等
`agents/<id>/sessions/`	会话存储目录（必须存在）

3. Bindings 路由

这是多 Agent 配置中最关键的部分。bindings 数组必须放在 配置文件根级别，不能嵌套在 channels.feishu 内部。

"bindings": [  {    "agentId": "main",    "match": { "channel": "feishu", "accountId": "default" }  },  {    "agentId": "developer",    "match": { "channel": "feishu", "accountId": "developer" }  },  {    "agentId": "writer",    "match": { "channel": "feishu", "accountId": "writer" }  },  {    "agentId": "analyst",    "match": { "channel": "feishu", "accountId": "analyst" }  },  {    "agentId": "ops",    "match": { "channel": "feishu", "accountId": "ops" }  },  {    "agentId": "ops",    "match": {      "channel": "feishu",      "peer": { "kind": "group", "id": "oc_指定群聊ID" }    }  }]

路由规则说明：

accountId

匹配：飞书消息通过哪个机器人（account）进来，就路由到对应 Agent

peer

匹配：针对特定群聊，无论通过哪个机器人收到消息，都路由到指定 Agent

peer

优先级高于 accountId

默认机器人的 accountId 固定为 "default"

4. 工具与协作

"tools": {  "profile": "full",  "agentToAgent": {    "enabled": true,    "allow": ["main", "developer", "writer", "analyst", "ops"]  },  "sessions": {    "visibility": "all"  }}

agentToAgent

：允许 Agent 之间互相调用，main 可以将任务分派给专业 Agent

sessions.visibility: "all"

：所有 Agent 共享会话可见性

5. 会话与记忆

"session": {  "dmScope": "per-account-channel-peer"},"hooks": {  "internal": {    "enabled": true,    "entries": {      "session-memory": { "enabled": true },      "command-logger": { "enabled": true },      "boot-md": { "enabled": true }    }  }}

per-account-channel-peer

：按账号+通道+对端隔离会话，保证不同机器人的私聊互不干扰

session-memory

：会话记忆持久化

boot-md

：启动时读取 BOOTSTRAP.md（首次初始化用）

第六步：准备 Agent 工作空间

每个 Agent 需要创建以下目录结构：

# 为每个 Agent 创建目录for agent in main developer writer analyst ops; do  mkdir -p ~/.openclaw/agents/$agent/agent  mkdir -p ~/.openclaw/agents/$agent/sessions    # ★ 必须存在，否则无法存储会话  mkdir -p ~/.openclaw/workspace-$agent/memorydone# main 的 workspace 路径不同mkdir -p ~/.openclaw/workspace/memory

在每个 Agent 的 workspace 中创建 SOUL.md，定义其人格：

# 示例：分析助手cat > ~/.openclaw/workspace-analyst/SOUL.md << 'EOF'# SOUL.md - Analyst Agent## 核心身份你是数据分析师，擅长从数据中发现模式和洞察。## 专业特质- 多维度思考，严谨方法论- 用数据讲故事，提供可行动的建议- 真相高于便利，洞察高于数据EOF

第七步：启动与验证

# 启动 Gatewayopenclaw gateway start# 检查状态openclaw status

验证输出应包含：

Channels│ Feishu   │ ON      │ OK     │ configured · accounts 5/5 │Sessions│ agent:analyst:feishu:analyst:di…  │ direct │ ... │ openrouter/auto ││ agent:developer:feishu:develope…  │ direct │ ... │ deepseek-chat   ││ agent:writer:feishu:writer:dire…  │ direct │ ... │ openrouter/auto │

关键检查项：

accounts 5/5

：5 个机器人全部连接成功

Session Key 前缀为 agent:<agentId>:feishu:<accountId>:...，不是全部 agent:main:...

每个 Agent 使用的模型与配置一致

群聊配置

将机器人加入群聊

在飞书群设置中添加机器人应用。

获取群聊 ID

启动 Gateway 后，在群里 @机器人发送一条消息，查看日志：

openclaw logs --follow

日志中会出现 oc_xxx 格式的群聊 ID。

配置群聊策略

"groups": {  "*": {    "requireMention": true        // 默认：需要 @机器人  },  "oc_你的群聊ID": {    "requireMention": false,       // 此群不需要 @    "groupPolicy": "open"          // 群内所有人可触发  }}

群聊路由到指定 Agent

在 bindings 中添加 peer 类型规则：

{  "agentId": "ops",  "match": {    "channel": "feishu",    "peer": { "kind": "group", "id": "oc_你的群聊ID" }  }}

踩坑记录

1. 默认机器人凭证位置

openclaw-lark 插件源码中，default 账号的 appId/appSecret只从 channels.feishu 顶层读取，不读取 accounts.default。如果放在 accounts.default 中，默认机器人将报 "not configured"。

openclaw doctor --fix 会建议把凭证移到 accounts.default，千万不要执行。

2. bindings 必须在配置根级别

bindings 数组必须放在 openclaw.json 的根级别：

{  "channels": { ... },  "bindings": [ ... ],     // ✅ 正确：根级别  "gateway": { ... }}

如果错放在 channels.feishu.bindings 中，路由引擎读不到，所有消息会全部落到 main Agent。

症状：所有 Agent 的 session key 都以 agent:main: 开头，其他 Agent 的 sessions 目录为空。

3. sessions 目录必须预创建

每个 Agent 的 ~/.openclaw/agents/<id>/sessions/ 目录必须存在，否则 Agent 无法创建和存储会话，导致沉默不响应。

4. 群聊需要 groupPolicy: "open"

如果想让群里的所有人都能触发机器人（不仅是 allowFrom 中的用户），需要在 groups 配置中显式设置 "groupPolicy": "open"。否则只有白名单用户能触发。

5. 已知限制

多 Agent 路由功能在 OpenClaw 2026.3.13 及以上版本才稳定支持

如果遇到路由异常，优先检查 bindings 位置和 sessions 目录

常用运维命令

# 查看状态openclaw status# 查看实时日志openclaw logs --follow# 重启 Gatewayopenclaw gateway restart# 查看飞书频道配置openclaw config get channels.feishu# 查看 bindings 配置openclaw config get bindings# 查看 Agent 列表openclaw config get agents.list# 诊断（不要加 --fix）openclaw doctor# 升级 OpenClawopenclaw update# 升级飞书插件openclaw plugins install @larksuite/openclaw-lark# 配对审批（pairing 模式下）openclaw pairing list feishuopenclaw pairing approve feishu <配对码># 查看会话openclaw sessions list

完整配置参考

以下为经过验证的完整 openclaw.json 结构（敏感值已脱敏）：

{  "auth": {    "profiles": {      "openrouter:default": {        "provider": "openrouter",        "mode": "api_key"      }    }  },  "models": {    "mode": "merge",    "providers": {      "deepseek": {        "baseUrl": "https://api.deepseek.com/v1",        "apiKey": "sk-your-key",        "api": "openai-completions",        "models": [          { "id": "deepseek-chat", "name": "DeepSeek Chat" },          { "id": "deepseek-reasoner", "name": "DeepSeek Reasoner" }        ]      }    }  },  "agents": {    "defaults": {      "compaction": { "mode": "safeguard" }    },    "list": [      {        "id": "main", "default": true, "name": "main",        "workspace": "~/.openclaw/workspace",        "agentDir": "~/.openclaw/agents/main/agent",        "model": "deepseek/deepseek-chat"      },      {        "id": "developer", "name": "developer",        "workspace": "~/.openclaw/workspace-developer",        "agentDir": "~/.openclaw/agents/developer/agent",        "model": "deepseek/deepseek-chat"      },      {        "id": "writer", "name": "writer",        "workspace": "~/.openclaw/workspace-writer",        "agentDir": "~/.openclaw/agents/writer/agent",        "model": "openrouter/auto"      },      {        "id": "analyst", "name": "analyst",        "workspace": "~/.openclaw/workspace-analyst",        "agentDir": "~/.openclaw/agents/analyst/agent",        "model": "openrouter/auto"      },      {        "id": "ops", "name": "运维助手",        "workspace": "~/.openclaw/workspace-ops",        "agentDir": "~/.openclaw/agents/ops/agent",        "model": "deepseek/deepseek-chat"      }    ]  },  "tools": {    "profile": "full",    "agentToAgent": {      "enabled": true,      "allow": ["main", "developer", "writer", "analyst", "ops"]    },    "sessions": { "visibility": "all" }  },  "messages": { "ackReactionScope": "group-mentions" },  "commands": {    "native": "auto",    "nativeSkills": "auto",    "restart": true  },  "session": { "dmScope": "per-account-channel-peer" },  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": true },        "boot-md": { "enabled": true }      }    }  },  "channels": {    "feishu": {      "enabled": true,      "domain": "feishu",      "streaming": true,      "appId": "cli_默认机器人AppID",      "appSecret": "默认机器人AppSecret",      "botName": "主助手",      "dmPolicy": "allowlist",      "allowFrom": ["ou_你的OpenID"],      "requireMention": true,      "groupPolicy": "allowlist",      "groupAllowFrom": ["oc_群聊ID"],      "accounts": {        "developer": {          "appId": "cli_xxx", "appSecret": "xxx", "botName": "开发助手"        },        "writer": {          "appId": "cli_xxx", "appSecret": "xxx", "botName": "写作助手"        },        "analyst": {          "appId": "cli_xxx", "appSecret": "xxx", "botName": "分析助手"        },        "ops": {          "appId": "cli_xxx", "appSecret": "xxx", "botName": "运维助手",          "dmPolicy": "open", "allowFrom": ["*"]        }      },      "groups": {        "*": { "requireMention": true },        "oc_群聊ID": { "requireMention": false, "groupPolicy": "open" }      }    }  },  "bindings": [    { "agentId": "main",      "match": { "channel": "feishu", "accountId": "default" } },    { "agentId": "developer", "match": { "channel": "feishu", "accountId": "developer" } },    { "agentId": "writer",    "match": { "channel": "feishu", "accountId": "writer" } },    { "agentId": "analyst",   "match": { "channel": "feishu", "accountId": "analyst" } },    { "agentId": "ops",       "match": { "channel": "feishu", "accountId": "ops" } },    { "agentId": "ops",       "match": { "channel": "feishu", "peer": { "kind": "group", "id": "oc_群聊ID" } } }  ],  "gateway": {    "port": 18789,    "mode": "local",    "bind": "loopback",    "auth": { "mode": "token", "token": "your-gateway-token" }  },  "plugins": {    "allow": ["openclaw-lark"],    "entries": {      "openclaw-lark": { "enabled": true }    }  }}

{{userData.name}}已认证