PicoClaw 接入飞书Lark渠道WebSocket 模式配置、源码原理与平台限制【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 通过事件驱动的 WebSocket/SDK 连接飞书Feishu国际版 Lark让机器人无需公网回调地址即可收发消息。本文围绕飞书渠道的配置项、应用开通流程与 64 位架构限制展开并结合 pkg/channels/feishu 下的源码实现讲清每条配置背后的实际作用、消息收发的底层机制与排查要点帮助你在中国内地或海外市场快速上线飞书机器人。飞书渠道是什么飞书是字节跳动推出的企业协作平台国际版名为 Lark覆盖中国与海外市场。PicoClaw 将飞书作为一个标准消息渠道接入用户通过飞书机器人私聊或群聊发消息Agent 接收并回复。与需要配置 Webhook 回调地址的传统集成不同PicoClaw 的飞书渠道使用事件驱动的 WebSocket/SDK 模式larkws.NewClient与飞书开放平台建立长连接事件实时推送到本地进程因此无需任何公网回调地址或 Webhook URL部署在局域网、内网或边缘设备上也能正常工作。从源码结构看飞书渠道的完整实现位于 pkg/channels/feishu按构建标签拆分为两个文件feishu_64.go64 位架构下的完整实现//go:build amd64 || arm64 || riscv64 || mips64 || ppc64feishu_32.go32 位架构下的占位 stub返回不支持错误详见下文「平台限制」。配置详解在 PicoClaw 的配置文件即channel_list中加入feishu条目即可启用完整示例见 config/config.example.json{ channel_list: { feishu: { enabled: true, type: feishu, app_id: cli_xxx, app_secret: xxx, encrypt_key: , verification_token: , allow_from: [] } } }配置项说明字段类型是否必填说明enabledbool是是否启用飞书渠道typestring是固定为feishu用于渠道类型识别app_idstring是飞书应用的 App ID以cli_开头app_secretstring是飞书应用的 App Secretencrypt_keystring否事件回调的加密密钥Encrypt Keyverification_tokenstring否事件 Webhook 验证使用的 Verification Tokenallow_fromarray否允许的用户 ID 白名单为空表示允许所有用户random_reaction_emojiarray否随机消息表情列表为空时使用默认的 Pin其中random_reaction_emoji与allow_from已在示例配置之外的渠道配置结构中出现此外你还可以在渠道级配置上添加通用的reasoning_channel_id与placeholder字段见 config/config.example.json 中的占位提示配置用于指定思考过程展示频道与思考中…占位提示文案。配置项的源码映射与环境变量这些字段在 pkg/config/config.go 的FeishuSettings结构体中定义并提供了对应的环境变量方便容器化或密钥管理场景下通过环境注入JSON 字段结构体字段环境变量app_idAppIDPICOCLAW_CHANNELS_FEISHU_APP_IDapp_secretAppSecretPICOCLAW_CHANNELS_FEISHU_APP_SECRETencrypt_keyEncryptKeyPICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEYverification_tokenVerificationTokenPICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKENrandom_reaction_emojiRandomReactionEmojiPICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJIis_larkIsLarkPICOCLAW_CHANNELS_FEISHU_IS_LARK注意app_secret、encrypt_key、verification_token均为SecureString类型在配置加载与安全审计中会被特殊处理相关逻辑可参考 pkg/config/security_integration_test.gois_lark用于切换服务域名为true时使用 Lark 国际版域名lark.LarkBaseUrl否则使用飞书国内版域名lark.FeishuBaseUrl对应Start中的域名选择逻辑见 feishu_64.go。渠道的注册与启动渠道工厂在包初始化时通过channels.RegisterFactory注册将配置解码为FeishuSettings后构造FeishuChannel见 init.go注册键为config.ChannelFeishu见 config_channel.go。启动时若app_id或app_secret为空会直接报错见 feishu_64.go因此这两个字段是渠道可运行的必要条件。开通与发布流程按以下步骤在飞书开放平台创建并发布应用然后启动 PicoClaw 即可与机器人对话登录飞书开放平台国内版 open.feishu.cn海外版为 Lark 开放平台创建企业自建应用在应用的「添加应用能力」中启用**机器人Bot**能力创建版本并发布应用——配置在发布后才生效未发布前修改不会进入线上环境在应用凭证页面获取App ID以cli_开头与App Secret将 App ID 与 App Secret 填入 PicoClaw 的配置文件即上文channel_list.feishu条目运行picoclaw gateway启动网关服务在飞书中搜索该机器人的名称进入会话后即可发送消息开始对话。关于安全性的补充说明PicoClaw 以 WebSocket/SDK 方式连接飞书不需要配置公网回调地址因此没有传统 Webhook 被扫描、伪造回调的风险面encrypt_key与verification_token为可选配置。若在飞书开放平台的事件订阅中开启了「加密」与「请求网址校验」则应同步填写这两个值生产环境建议开启事件加密事件分发生效链路为飞书事件 → WebSocket 长连接 → SDK 内置EventDispatcher其中NewEventDispatcher(VerificationToken, EncryptKey)负责事件的验签与解密见 feishu_64.go未配置时传入空字符串即可。消息收发的底层实现回复使用交互式卡片失败自动降级为纯文本PicoClaw 发送回复时优先构造飞书交互式卡片Interactive CardJSON 2.0卡片内使用markdown元素承载内容见 common.go 的buildMarkdownCardschema 为2.0支持完整 CommonMark 语法。这样 Agent 的 Markdown 输出标题、列表、代码块、表格等能获得较好的排版效果。发送逻辑见 feishu_64.go 的Send采用降级策略优先以交互式卡片发送若卡片发送失败且错误码包含11310卡片表格等元素超过限制自动降级为普通文本消息发送卡片构建失败或文本发送仍失败时返回相应错误。同时渠道还实现了消息编辑EditMessage通过Message.Patch原地更新卡片、消息删除DeleteMessage与占位提示SendPlaceholder配合placeholder配置支持在 Agent 思考过程中先发出Thinking…占位卡片再逐步更新为最终回答。表情反应与 allow_from 白名单渠道实现了ReactionCapable接口收到新消息时会从random_reaction_emoji中随机挑选一个表情如Pin、THUMBSUP等飞书emoji_type加到消息上列表为空或全为空字符串时默认使用Pin见 feishu_64.go。自定义表情请使用飞书开放平台「消息表情」文档中的合法 emoji 类型键。allow_from白名单在渠道构造时通过channels.NewBaseChannel(..., bc.AllowFrom, ...)传入见 feishu_64.go。入站消息会先做白名单校验未通过的发送者消息会被直接丢弃且在下载媒体资源之前就拦截避免无谓的网络 IO见 feishu_64.go。入站消息提及、群组触发与多媒体入站消息处理handleMessageReceive见 feishu_64.go的主要逻辑区分私聊p2p与群聊群聊中只有在机器人被 提及或满足群组触发规则时才响应触发前会先调用ShouldRespondInGroup识别 提及依赖机器人自身的open_id启动时会调用GET /open-apis/bot/v3/info获取并缓存见fetchBotOpenID拿不到时 检测不可用但渠道仍可运行清理飞书注入的_user_N占位符stripMentionPlaceholders见 common.go避免这些占位符混入给 LLM 的文本文本消息提取text字段富文本post、交互卡片消息则将原始 JSON 直接传给 LLM保留结构化信息图片/文件/音频/视频消息会解析image_key、file_key并通过飞书 API 下载到本地媒体库下载失败会回退到Image.Get接口兼容不同的权限范围再以[image: photo]、[file]等标签追加到内容中见appendMediaTags与downloadInboundMedia回复/话题消息会附带父消息上下文prependReplyContext群聊、租户信息TenantKey会一并写入入站上下文。出站媒体先上传再发送SendMedia会先将图片/文件上传到飞书换取image_key/file_key再发送对应类型的消息见sendImage/sendFile。文件类型会做映射audio→opus、video→mp4其余为stream见 feishu_64.go且支持携带首段媒体说明文字作为 caption。Token 缓存失效自愈飞书tenant_access_token有效期约 2 小时。Lark SDK 内置重试在遇到错误码99991663租户 token 无效/被吊销时不会清理自身缓存会导致后续请求持续失败。PicoClaw 因此自建了可失效的tokenCache在收到该错误码时主动InvalidateAll()清空缓存让下一次请求自动获取新 token见 feishu_64.go 与invalidateTokenOnAuthError。平台限制⚠️飞书渠道不支持 32 位设备。飞书 SDK 仅提供 64 位构建产物。运行在 armv6、armv7、mipsle 等 32 位架构上的设备无法使用飞书渠道。这一限制在源码中以构建标签方式强制实现只有amd64、arm64、riscv64、mips64、ppc64这五类 64 位架构会编译 feishu_64.go 的完整实现其余架构编译 feishu_32.goNewFeishuChannel直接返回错误feishu channel is not supported on 32-bit architectures (armv7l, 386, etc.). Please use a 64-bit system or disable feishu in your configStart/Stop/Send等接口均为 stub。因此在 32 位设备上需要消息渠道时请改用 Telegram、Discord 或 OneBot 等渠道或将系统升级到 64 位后再启用飞书。常见排查要点机器人不回复确认应用已发布配置发布后才生效、app_id/app_secret非空并检查picoclaw gateway启动日志中是否出现Feishu channel started (websocket mode)群聊不响应群聊需要 机器人或满足群组触发规则若日志提示Bot open_id unknown说明启动时获取机器人 open_id 失败 提及检测不可用请检查应用权限与网络 后内容仍带_user_N占位符清理逻辑依赖飞书事件中的mentions字段若事件未携带该字段残留占位符可能进入文本可在排查时关注事件原文回复排版异常若交互卡片因元素超限错误码11310发送失败渠道会自动降级为纯文本日志中会记录Card send failed (table limit), falling back to text message偶发全部 API 失败可能是tenant_access_token失效且 SDK 缓存未清理PicoClaw 已针对错误码99991663内置缓存失效自愈升级到包含该修复的版本即可32 位设备报渠道不支持属预期行为见上文「平台限制」。通过以上配置与原理你可以在无需公网回调的前提下将 PicoClaw Agent 接入飞书Lark生态覆盖私聊、群聊、多媒体消息与表情互动等场景。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PicoClaw 接入飞书（Lark）渠道：WebSocket 模式配置、源码原理与平台限制
PicoClaw 接入飞书Lark渠道WebSocket 模式配置、源码原理与平台限制【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 通过事件驱动的 WebSocket/SDK 连接飞书Feishu国际版 Lark让机器人无需公网回调地址即可收发消息。本文围绕飞书渠道的配置项、应用开通流程与 64 位架构限制展开并结合 pkg/channels/feishu 下的源码实现讲清每条配置背后的实际作用、消息收发的底层机制与排查要点帮助你在中国内地或海外市场快速上线飞书机器人。飞书渠道是什么飞书是字节跳动推出的企业协作平台国际版名为 Lark覆盖中国与海外市场。PicoClaw 将飞书作为一个标准消息渠道接入用户通过飞书机器人私聊或群聊发消息Agent 接收并回复。与需要配置 Webhook 回调地址的传统集成不同PicoClaw 的飞书渠道使用事件驱动的 WebSocket/SDK 模式larkws.NewClient与飞书开放平台建立长连接事件实时推送到本地进程因此无需任何公网回调地址或 Webhook URL部署在局域网、内网或边缘设备上也能正常工作。从源码结构看飞书渠道的完整实现位于 pkg/channels/feishu按构建标签拆分为两个文件feishu_64.go64 位架构下的完整实现//go:build amd64 || arm64 || riscv64 || mips64 || ppc64feishu_32.go32 位架构下的占位 stub返回不支持错误详见下文「平台限制」。配置详解在 PicoClaw 的配置文件即channel_list中加入feishu条目即可启用完整示例见 config/config.example.json{ channel_list: { feishu: { enabled: true, type: feishu, app_id: cli_xxx, app_secret: xxx, encrypt_key: , verification_token: , allow_from: [] } } }配置项说明字段类型是否必填说明enabledbool是是否启用飞书渠道typestring是固定为feishu用于渠道类型识别app_idstring是飞书应用的 App ID以cli_开头app_secretstring是飞书应用的 App Secretencrypt_keystring否事件回调的加密密钥Encrypt Keyverification_tokenstring否事件 Webhook 验证使用的 Verification Tokenallow_fromarray否允许的用户 ID 白名单为空表示允许所有用户random_reaction_emojiarray否随机消息表情列表为空时使用默认的 Pin其中random_reaction_emoji与allow_from已在示例配置之外的渠道配置结构中出现此外你还可以在渠道级配置上添加通用的reasoning_channel_id与placeholder字段见 config/config.example.json 中的占位提示配置用于指定思考过程展示频道与思考中…占位提示文案。配置项的源码映射与环境变量这些字段在 pkg/config/config.go 的FeishuSettings结构体中定义并提供了对应的环境变量方便容器化或密钥管理场景下通过环境注入JSON 字段结构体字段环境变量app_idAppIDPICOCLAW_CHANNELS_FEISHU_APP_IDapp_secretAppSecretPICOCLAW_CHANNELS_FEISHU_APP_SECRETencrypt_keyEncryptKeyPICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEYverification_tokenVerificationTokenPICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKENrandom_reaction_emojiRandomReactionEmojiPICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJIis_larkIsLarkPICOCLAW_CHANNELS_FEISHU_IS_LARK注意app_secret、encrypt_key、verification_token均为SecureString类型在配置加载与安全审计中会被特殊处理相关逻辑可参考 pkg/config/security_integration_test.gois_lark用于切换服务域名为true时使用 Lark 国际版域名lark.LarkBaseUrl否则使用飞书国内版域名lark.FeishuBaseUrl对应Start中的域名选择逻辑见 feishu_64.go。渠道的注册与启动渠道工厂在包初始化时通过channels.RegisterFactory注册将配置解码为FeishuSettings后构造FeishuChannel见 init.go注册键为config.ChannelFeishu见 config_channel.go。启动时若app_id或app_secret为空会直接报错见 feishu_64.go因此这两个字段是渠道可运行的必要条件。开通与发布流程按以下步骤在飞书开放平台创建并发布应用然后启动 PicoClaw 即可与机器人对话登录飞书开放平台国内版 open.feishu.cn海外版为 Lark 开放平台创建企业自建应用在应用的「添加应用能力」中启用**机器人Bot**能力创建版本并发布应用——配置在发布后才生效未发布前修改不会进入线上环境在应用凭证页面获取App ID以cli_开头与App Secret将 App ID 与 App Secret 填入 PicoClaw 的配置文件即上文channel_list.feishu条目运行picoclaw gateway启动网关服务在飞书中搜索该机器人的名称进入会话后即可发送消息开始对话。关于安全性的补充说明PicoClaw 以 WebSocket/SDK 方式连接飞书不需要配置公网回调地址因此没有传统 Webhook 被扫描、伪造回调的风险面encrypt_key与verification_token为可选配置。若在飞书开放平台的事件订阅中开启了「加密」与「请求网址校验」则应同步填写这两个值生产环境建议开启事件加密事件分发生效链路为飞书事件 → WebSocket 长连接 → SDK 内置EventDispatcher其中NewEventDispatcher(VerificationToken, EncryptKey)负责事件的验签与解密见 feishu_64.go未配置时传入空字符串即可。消息收发的底层实现回复使用交互式卡片失败自动降级为纯文本PicoClaw 发送回复时优先构造飞书交互式卡片Interactive CardJSON 2.0卡片内使用markdown元素承载内容见 common.go 的buildMarkdownCardschema 为2.0支持完整 CommonMark 语法。这样 Agent 的 Markdown 输出标题、列表、代码块、表格等能获得较好的排版效果。发送逻辑见 feishu_64.go 的Send采用降级策略优先以交互式卡片发送若卡片发送失败且错误码包含11310卡片表格等元素超过限制自动降级为普通文本消息发送卡片构建失败或文本发送仍失败时返回相应错误。同时渠道还实现了消息编辑EditMessage通过Message.Patch原地更新卡片、消息删除DeleteMessage与占位提示SendPlaceholder配合placeholder配置支持在 Agent 思考过程中先发出Thinking…占位卡片再逐步更新为最终回答。表情反应与 allow_from 白名单渠道实现了ReactionCapable接口收到新消息时会从random_reaction_emoji中随机挑选一个表情如Pin、THUMBSUP等飞书emoji_type加到消息上列表为空或全为空字符串时默认使用Pin见 feishu_64.go。自定义表情请使用飞书开放平台「消息表情」文档中的合法 emoji 类型键。allow_from白名单在渠道构造时通过channels.NewBaseChannel(..., bc.AllowFrom, ...)传入见 feishu_64.go。入站消息会先做白名单校验未通过的发送者消息会被直接丢弃且在下载媒体资源之前就拦截避免无谓的网络 IO见 feishu_64.go。入站消息提及、群组触发与多媒体入站消息处理handleMessageReceive见 feishu_64.go的主要逻辑区分私聊p2p与群聊群聊中只有在机器人被 提及或满足群组触发规则时才响应触发前会先调用ShouldRespondInGroup识别 提及依赖机器人自身的open_id启动时会调用GET /open-apis/bot/v3/info获取并缓存见fetchBotOpenID拿不到时 检测不可用但渠道仍可运行清理飞书注入的_user_N占位符stripMentionPlaceholders见 common.go避免这些占位符混入给 LLM 的文本文本消息提取text字段富文本post、交互卡片消息则将原始 JSON 直接传给 LLM保留结构化信息图片/文件/音频/视频消息会解析image_key、file_key并通过飞书 API 下载到本地媒体库下载失败会回退到Image.Get接口兼容不同的权限范围再以[image: photo]、[file]等标签追加到内容中见appendMediaTags与downloadInboundMedia回复/话题消息会附带父消息上下文prependReplyContext群聊、租户信息TenantKey会一并写入入站上下文。出站媒体先上传再发送SendMedia会先将图片/文件上传到飞书换取image_key/file_key再发送对应类型的消息见sendImage/sendFile。文件类型会做映射audio→opus、video→mp4其余为stream见 feishu_64.go且支持携带首段媒体说明文字作为 caption。Token 缓存失效自愈飞书tenant_access_token有效期约 2 小时。Lark SDK 内置重试在遇到错误码99991663租户 token 无效/被吊销时不会清理自身缓存会导致后续请求持续失败。PicoClaw 因此自建了可失效的tokenCache在收到该错误码时主动InvalidateAll()清空缓存让下一次请求自动获取新 token见 feishu_64.go 与invalidateTokenOnAuthError。平台限制⚠️飞书渠道不支持 32 位设备。飞书 SDK 仅提供 64 位构建产物。运行在 armv6、armv7、mipsle 等 32 位架构上的设备无法使用飞书渠道。这一限制在源码中以构建标签方式强制实现只有amd64、arm64、riscv64、mips64、ppc64这五类 64 位架构会编译 feishu_64.go 的完整实现其余架构编译 feishu_32.goNewFeishuChannel直接返回错误feishu channel is not supported on 32-bit architectures (armv7l, 386, etc.). Please use a 64-bit system or disable feishu in your configStart/Stop/Send等接口均为 stub。因此在 32 位设备上需要消息渠道时请改用 Telegram、Discord 或 OneBot 等渠道或将系统升级到 64 位后再启用飞书。常见排查要点机器人不回复确认应用已发布配置发布后才生效、app_id/app_secret非空并检查picoclaw gateway启动日志中是否出现Feishu channel started (websocket mode)群聊不响应群聊需要 机器人或满足群组触发规则若日志提示Bot open_id unknown说明启动时获取机器人 open_id 失败 提及检测不可用请检查应用权限与网络 后内容仍带_user_N占位符清理逻辑依赖飞书事件中的mentions字段若事件未携带该字段残留占位符可能进入文本可在排查时关注事件原文回复排版异常若交互卡片因元素超限错误码11310发送失败渠道会自动降级为纯文本日志中会记录Card send failed (table limit), falling back to text message偶发全部 API 失败可能是tenant_access_token失效且 SDK 缓存未清理PicoClaw 已针对错误码99991663内置缓存失效自愈升级到包含该修复的版本即可32 位设备报渠道不支持属预期行为见上文「平台限制」。通过以上配置与原理你可以在无需公网回调的前提下将 PicoClaw Agent 接入飞书Lark生态覆盖私聊、群聊、多媒体消息与表情互动等场景。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考