配置参考
完整的 channels.feishu 键列表及其默认值,以及 webhook 路径规则。
配置参考¶
完整配置:网关配置
| 设置 | 描述 | 默认值 |
|---|---|---|
channels.feishu.enabled |
启用/禁用该频道 | true |
channels.feishu.domain |
API 域名(feishu、lark 或 https:// 基础 URL) |
feishu |
channels.feishu.connectionMode |
事件传输方式(websocket 或 webhook) |
websocket |
channels.feishu.defaultAccount |
出站路由的默认账户 | default |
channels.feishu.verificationToken |
webhook 模式必需 | - |
channels.feishu.encryptKey |
webhook 模式必需 | - |
channels.feishu.webhookPath |
规范的 HTTP 请求路径(必须以 / 开头) |
/feishu/events |
channels.feishu.legacyWebhook |
显式转发监听器:{ port, host? };省略或为 false 时不打开监听器,受账户继承影响 |
none |
channels.feishu.accounts.<id>.appId |
应用 ID | - |
channels.feishu.accounts.<id>.appSecret |
应用密钥 | - |
channels.feishu.accounts.<id>.domain |
按账户覆盖域名 | feishu |
channels.feishu.accounts.<id>.replyToMode |
按账户的回复引用模式 | inherited |
channels.feishu.accounts.<id>.requireMentionInBotThreads |
按账户要求在本机器人发起的线程中提及 | inherited |
channels.feishu.accounts.<id>.tts |
按账户覆盖 TTS | tts |
channels.feishu.accounts.<id>.actions.sticker |
按账户覆盖贴纸操作 | inherited |
channels.feishu.dmPolicy |
私信策略(pairing、allowlist、open) |
pairing |
channels.feishu.allowFrom |
私信允许列表(open_id 列表) | - |
channels.feishu.groupPolicy |
群组策略(open、allowlist、disabled) |
allowlist |
channels.feishu.groupAllowFrom |
群组允许列表 | - |
channels.feishu.groupSenderAllowFrom |
应用于所有群组的发送者允许列表 | - |
channels.feishu.requireMention |
在群组中要求 @提及 | true(策略为 open 时为 false) |
channels.feishu.requireMentionInBotThreads |
覆盖本机器人发起的线程中的提及;参见 访问控制 | 现有提及行为 |
| 设置 | 描述 | 默认值 |
|---|---|---|
channels.feishu.allowBots |
接受提及此机器人的其他机器人,并带有机器人循环保护 | false |
channels.feishu.groups.<chat_id>.requireMention |
按群组覆盖 @提及;显式 ID 也会在允许列表模式下允许该群组 | 继承 |
channels.feishu.groups.<chat_id>.requireMentionInBotThreads |
在此机器人发起的线程中按群组要求提及 | 继承 |
channels.feishu.groups.<chat_id>.enabled |
启用/禁用特定群组 | true |
channels.feishu.groups.<chat_id>.allowFrom |
按群组的发送者允许列表(覆盖 groupSenderAllowFrom) |
- |
channels.feishu.groupSessionScope |
群组会话映射(group、group_sender、group_topic、group_topic_sender) |
group |
channels.feishu.replyToMode |
回复引用模式(off、first、all、batched) |
all |
channels.feishu.replyInThread |
机器人回复创建/继续话题线程(disabled、enabled) |
disabled |
channels.feishu.reactionNotifications |
入站表情回应事件(off、own、all) |
own |
channels.feishu.actions.sticker |
启用已接收贴纸的发送以及已配置的贴纸搜索 | false |
channels.feishu.stickerSets |
可搜索的已接收贴纸键和关键词,按机器人应用 ID 分组 | 无 |
channels.feishu.vcAutoJoin |
在普通私信授权后加入受邀的 VC 会议 | false |
channels.feishu.dynamicAgentCreation.enabled |
启用按用户自动创建代理 | false |
channels.feishu.dynamicAgentCreation.workspaceTemplate |
动态代理工作区的路径模板 | ~/.openclaw/workspace-{agentId} |
channels.feishu.dynamicAgentCreation.agentDirTemplate |
代理目录名称模板 | ~/.openclaw/agents/{agentId}/agent |
channels.feishu.dynamicAgentCreation.maxAgents |
要创建的最大动态代理数量 | 无限制 |
channels.feishu.textChunkLimit |
消息分块大小 | 4000 |
channels.feishu.streaming.chunkMode |
分块拆分(length 或 newline) |
length |
channels.feishu.mediaMaxMb |
媒体大小限制 | 30 |
channels.feishu.renderMode |
回复渲染(auto、raw、card) |
auto |
channels.feishu.streaming.mode |
流式卡片输出(partial 或 off) |
partial |
channels.feishu.streaming.block.enabled |
已完成块回复流式传输 | false |
channels.feishu.typingIndicator |
发送正在输入表情回应 | true |
| 设置 | 描述 | 默认值 |
|---|---|---|
channels.feishu.resolveSenderNames |
解析发送者显示名称 | true |
channels.feishu.configWrites |
允许通道发起的配置写入(动态智能体所需) | true |
channels.feishu.tools.doc |
启用文档工具 | true |
channels.feishu.tools.chat |
启用聊天信息工具 | true |
channels.feishu.tools.wiki |
启用知识库工具(需要 doc) |
true |
channels.feishu.tools.drive |
启用云存储工具 | true |
channels.feishu.tools.perm |
启用权限管理工具 | false |
channels.feishu.tools.scopes |
启用应用 scopes 诊断工具 | true |
channels.feishu.tools.bitable |
启用 Bitable/Base 工具 | true |
channels.feishu.accounts.<id>.tools.bitable |
按账户的 Bitable/Base 工具开关 | 继承 |
在 Webhook 模式下,channels.feishu.webhookPath 和
channels.feishu.accounts.<id>.webhookPath 都必须是规范的 HTTP 请求路径,
以 / 开头,例如 /feishu/events。支持可选的查询字符串,且必须完全匹配。
完整 URL、相对路径、URL 片段、点段,以及未编码的空格或 Unicode 都会被拒绝。
如果现有配置包含非规范路径,请在启动 Gateway 之前运行 openclaw doctor --fix
进行修复。
Gateway Webhook 路由¶
Webhook 模式使用 Gateway HTTP 监听器(gateway.port,通常为 18789)
在 webhookPath 处,通常为 /feishu/events。请配置公开的 Feishu 回调
URL 或反向代理,以访问该 Gateway 端口和路径。该路由会验证 Feishu 签名,
并且不需要 Gateway bearer 认证。当各账户的加密密钥不同时,账户可以共享
同一路径;在 Gateway 端口上出现歧义签名时,系统会拒绝请求,而不是选择任意
账户。共享同一路径和加密密钥的旧账户在其各自独立的显式旧版监听器上
仍可区分。在将这些账户的回调迁移到共享 Gateway 端口之前,请为这些账户配置
不同的加密密钥或 Webhook 路径。
共享同一 Gateway 路径的账户会共享其未认证请求速率和进行中正文读取预算,
因为签名验证需要完整正文。请使用不同的 webhookPath 路径名以获得独立预算。
受信任的旧版端点即使路径相同,也会保留独立的进行中容量。
新安装不会打开单独的 Webhook 端口。在现有安装中,Doctor 会为依赖隐式端点的
已启用 Webhook 账户一次性固定 legacyWebhook: { port: 3000, host: "127.0.0.1" }。
Gateway 拥有此显式监听器,并将请求转发到相同的插件路由和签名验证器。
设置 legacyWebhook: { port: 3100, host: "127.0.0.1" } 可选择其他端点。
省略对象 host 时会绑定到 127.0.0.1;显式主机,包括通配符地址,会被保留。
账户条目继承根设置,并且 accounts.<id>.legacyWebhook: false 会禁用该账户的转发。
Feishu 需要 OpenClaw 2026.9.8 或更高版本。Gateway 拥有所有 Webhook 监听器,
并且只要另一个账户仍在使用该端点,共享的旧版套接字就会保持打开。
在账户关闭时,已认证响应最多可完成五秒,与之前监听器的关闭宽限期一致。
未完成的响应会在该截止时间关闭;其他账户保留其路由和监听器。
在该宽限期内,针对正在停止账户的签名正确的回调会收到可重试的 503,
除非活动后续账户已经接受其签名。
插件的 Doctor 迁移会将 webhookPort 和 webhookHost
移动到 legacyWebhook: { port, host },当只设置了一个键时,保留有效的旧默认值。
常规配置备份会保护原始设置。现有的规范 legacyWebhook 设置(包括 false)优先。
一次性固定会保留省略了这两个旧设置的现有安装;它需要先前运行的证据,
并且不会应用于全新安装。
当从带有这些旧键的 2026.9.6 主机更新时,先将 OpenClaw 核心更新到 2026.9.8 或更高版本,其中包含 插件更新迁移修复。 然后显式更新任何已固定版本的 Feishu 包到你选择的发布版本。核心更新器会保留显式的插件版本固定。更新后的安装程序会在激活替换包之前应用 Feishu 的迁移;已发布的 2026.9.6 安装程序会在运行该修复之前拒绝新架构。被拒绝的仅插件更新会保留之前的安装和设置不变。
已弃用的 TypeScript webhookPort 和 webhookHost 输入字段在下一个 Plugin SDK 主要版本之前保持源码兼容。运行时配置使用 legacyWebhook;运行 openclaw doctor --fix 以迁移旧键。
若要仅使用 Gateway 端口,请将 Feishu 回调 URL 或反向代理上游更新为 Gateway 端口和 webhookPath,验证投递,然后移除 legacyWebhook 固定。保留 meta.migrations.webhookListeners,Doctor 会将其与固定项一起保存,以便后续运行不会重新创建它。有关包含的配置源和只读配置源,请参阅 webhook 迁移。使用 accounts.<id>.legacyWebhook: false 可覆盖继承的根监听器。启动和 Doctor 会打印目标地址和移除说明。Doctor 将健康端点指导作为信息呈现,将路径冲突作为警告呈现;已禁用的账户和 WebSocket 账户不会收到 webhook 备注。OpenClaw 无法更新存储在 Feishu 控制台中的回调 URL。
确切的 Gateway 检查路径(/health、/healthz、/ready、/readyz、/startup 和 /startupz,包括查询字符串)无法在 Gateway 端口上接收 Feishu 回调。如果没有显式的旧版监听器,webhook 启动会拒绝这些路径并指明替换路径。启用时,旧版监听器会继续为旧路径提供服务。将 webhookPath 更改为 /feishu/events(或其他未保留路径),更新 Feishu 回调 URL 或反向代理路径,并在移除 legacyWebhook 固定之前验证 Gateway 上的投递。嵌套在检查路径之下的路径不会被此规则保留。
/api/channels 下的路径需要 Gateway 身份验证,并且无法在 Gateway 端口上接收普通 Feishu 回调。这也适用于该前缀的编码形式。启动和 Doctor 会给出相同的路径更改说明;旧版监听器会在路径和外部回调或代理迁移之前保持这些回调可用。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw