阳阳的技术博客：OpenClaw、DevOps与AI辅助Web开发实践

引言

OpenClaw v2026.4.8 对飞书通道配置 Schema 进行了系统性重构，废弃了一批历史遗留字段，同时引入了更灵活的连接模式、细粒度策略控制和多账号管理体系。本文基于源码 extensions/feishu/src/config-schema.ts，逐章节详解所有配置项的含义、类型、默认值及使用场景，帮助开发者在升级时少走弯路。

飞书通道的两种连接模式

飞书通道支持两种与飞书服务端建立连接的方式，通过 connectionMode 字段切换：

连接模式	配置值	说明
WebSocket（推荐）	`websocket`	长连接模式，OpenClaw 主动连接飞书事件服务器，无需暴露公网端口。默认为此模式
Webhook	`webhook`	被动接收模式，需要配置 `webhookHost`、`webhookPort` 并暴露公网入口，适合已有限制 WS 访问的网络环境

typescript

// WebSocket 模式（默认）
connectionMode: "websocket"

// Webhook 模式需额外配置
connectionMode: "webhook"
webhookPath: "/feishu/events"      // 默认值
webhookHost: "0.0.0.0"             // 监听地址
webhookPort: 8080                 // 监听端口

提示：如果使用 Webhook 模式，还需要配置 encryptKey 和 verificationToken，这两个字段在 WebSocket 模式下可选。

顶级配置（FeishuConfigSchema）

以下是飞书通道的完整顶级配置结构：

typescript

{
  enabled: boolean,                    // 是否启用此通道
  defaultAccount: string,              // 默认账号 ID（多账号模式）
  appId: string,                       // 应用 ID（单账号模式）
  appSecret: Secret,                   // 应用密钥
  encryptKey: Secret,                  // 加密密钥（webhook 模式需要）
  verificationToken: Secret,           // 验证令牌（webhook 模式需要）
  domain: "feishu" | "lark",           // 域名，默认 "feishu"
  connectionMode: "websocket" | "webhook", // 连接模式，默认 "websocket"
  webhookPath: string,                 // webhook 路径，默认 "/feishu/events"
  dmPolicy: "open" | "pairing" | "allowlist", // DM 策略，默认 "pairing"
  groupPolicy: "open" | "allowlist" | "disabled", // 群组策略，默认 "allowlist"
  allowFrom: string[],                 // 允许发送者的用户 ID 白名单
  groupAllowFrom: string[],            // 群组白名单
  groupSenderAllowFrom: string[],      // 群组发送者白名单
  requireMention: boolean,             // 是否需要 @ 机器人
  groupSessionScope: "group" | "group_sender" | "group_topic" | "group_topic_sender",
  replyInThread: "disabled" | "enabled",
  reactionNotifications: "off" | "own" | "all",  // 默认 "own"
  typingIndicator: boolean,             // 显示正在输入，默认 true
  resolveSenderNames: boolean,         // 解析发送者名称，默认 true
  streaming: boolean,                  // 启用流式卡片回复
  renderMode: "auto" | "raw" | "card", // 消息渲染模式
  blockStreamingCoalesce: BlockStreamingCoalesceSchema,
  historyLimit: number,                // 历史消息限制
  dmHistoryLimit: number,              // DM 历史限制
  textChunkLimit: number,              // 文本块大小限制
  chunkMode: "length" | "newline",     // 块模式
  mediaMaxMb: number,                 // 媒体文件最大 MB
  httpTimeoutMs: number,              // HTTP 超时（毫秒），最大 300000
  heartbeat: ChannelHeartbeatVisibilitySchema,
  markdown: MarkdownConfigSchema,
  tools: FeishuToolsConfigSchema,
  actions: object,
  configWrites: boolean,              // 允许配置写入
  dynamicAgentCreation: DynamicAgentCreationSchema,
  capabilities: string[],             // 功能列表
  groups: Record<string, FeishuGroupSchema>,  // 各群组配置
  dms: Record<string, object>,        // 各 DM 配置
  accounts: Record<string, FeishuAccountConfigSchema>, // 多账号配置
}

核心策略配置

DM 策略（dmPolicy） 控制私聊消息的处理方式：

策略值	行为
`open`	允许任何人向机器人发私信
`pairing`	默认，仅配对用户可以发私信
`allowlist`	仅 `allowFrom` 列表中的用户可以发私信

群组策略（groupPolicy） 控制群组消息的处理方式：

策略值	行为
`open`	允许所有群组
`allowlist`	默认，仅 `groupAllowFrom` 中的群组可用
`disabled`	完全禁用群组消息

注意：groupSenderAllowFrom 用于进一步限制特定群组中的特定用户，而非整群。

子配置结构详解

流式响应合并：blockStreamingCoalesce

流式卡片回复场景下，可通过 blockStreamingCoalesce 控制消息块的合并延迟策略：

typescript

blockStreamingCoalesce: {
  enabled: boolean,      // 是否启用
  minDelayMs: number,    // 最小延迟（毫秒）
  maxDelayMs: number,    // 最大延迟（毫秒）
}

合理配置此参数可以在流畅性和响应速度之间取得平衡。

Markdown 渲染：markdown

typescript

markdown: {
  mode: "native" | "escape" | "strip",  // 原生 / 转义 / 剥离
  tableMode: "native" | "ascii" | "simple",  // 表格渲染模式
}

飞书的 Markdown 支持有限，建议根据消息内容复杂度选择合适的 mode，避免格式错乱。

工具权限：tools

typescript

tools: {
  doc: boolean,      // 文档操作（默认 true）
  chat: boolean,     // 聊天信息查询（默认 true）
  wiki: boolean,     // 知识库操作（默认 true，需要 doc）
  drive: boolean,    // 云存储操作（默认 true）
  perm: boolean,     // 权限管理（默认 false，敏感操作）
  scopes: boolean,   // 应用 scopes 诊断（默认 true）
}

动态 Agent 创建：dynamicAgentCreation

typescript

dynamicAgentCreation: {
  enabled: boolean,
  workspaceTemplate: string,  // 工作空间模板
  agentDirTemplate: string,   // Agent 目录模板
  maxAgents: number,          // 最大 Agent 数量
}

群组配置（FeishuGroupSchema）

每个群组可以拥有独立的配置，覆盖全局默认设置：

typescript

{
  requireMention: boolean,           // 是否需要 @ 机器人
  tools: ToolPolicySchema,           // 工具策略（allow / deny）
  skills: string[],                  // 技能列表
  enabled: boolean,                  // 是否启用
  allowFrom: string[],              // 允许的用户 ID
  systemPrompt: string,             // 系统提示词
  groupSessionScope: enum,          // 会话范围
  topicSessionMode: enum,           // 话题模式
  replyInThread: enum,              // 线程回复
}

提示：通过 groups 记录可以为不同群组定制完全不同的行为，是实现多租户隔离的有效手段。

多账号配置（FeishuAccountConfigSchema）

typescript

{
  enabled: boolean,
  name: string,              // 显示名称
  appId: string,
  appSecret: Secret,
  encryptKey: Secret,
  verificationToken: Secret,
  domain: enum,
  connectionMode: enum,
  webhookPath: string,
  // 继承所有 FeishuSharedConfigShape 配置
}

通过 accounts 字典配置多个飞书应用实例，适合需要同时服务多个飞书组织或隔离不同业务线的场景。

已被移除的旧字段

以下字段已在 v2026.4.8 中废弃，请勿继续使用：

旧字段	替代方案
`threadSession`	`groupSessionScope`
`replyMode`	`replyInThread`
`blockStreaming`	`blockStreamingCoalesce`
`footer`	已删除
`ignoreBotMessages`	已删除
`enableMessageIdempotency`	已删除
`requestTimeout`	`httpTimeoutMs`
`wsTimeout`	已删除
各 account 下的 `botName`	已删除

默认值速查表

配置项	默认值
`domain`	`"feishu"`
`connectionMode`	`"websocket"`
`webhookPath`	`"/feishu/events"`
`dmPolicy`	`"pairing"`
`groupPolicy`	`"allowlist"`
`reactionNotifications`	`"own"`
`typingIndicator`	`true`
`resolveSenderNames`	`true`

结语

v2026.4.8 的飞书通道 Schema 重构围绕灵活性和清晰度两个目标展开。连接模式与策略控制的解耦、群组级和账号级配置的分离、以及对历史遗留字段的系统性清理，让整个配置的扩展性和可维护性都上了一个台阶。建议已有配置的用户在升级后检查是否仍在使用已废弃字段，及时迁移以避免潜在问题。