无需公网IP接入PromptX：飞书机器人WebSocket长连接完整教程

无需公网IP接入PromptX飞书机器人WebSocket长连接完整教程【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptXPromptX 是一款领先的 AI 智能体上下文平台。本教程介绍如何用飞书机器人 WebSocket 长连接模式将 PromptX 桌面客户端接入飞书——不需要公网 IP、不需要域名、不需要内网穿透打开飞书就能直接和 AI 智能体对话。为什么不需要公网 IP飞书 WebSocket 长连接原理传统的机器人接入方式Webhook 回调要求你有一台带公网 IP 的服务器来接收飞书推送的消息这对个人用户几乎是门槛。而 PromptX 采用的长连接WebSocket模式完全反转了连接方向由你的 PromptX 客户端主动向外建立一条加密 WebSocket 连接连到飞书开放平台用户发给机器人的消息由飞书平台通过这条已建立的长连接下发到本地本地程序再调用飞书消息 API 把 AI 的回复发回会话。整个过程就像打电话你主动拨出去对方就能随时跟你说话而不需要你家装一部对外公开的电话机。因此家里电脑、公司内网、甚至移动宽带都可以直接接入只要机器能访问互联网即可。核心实现在 FeishuBot.ts 中它基于飞书官方larksuiteoapi/node-sdk提供的WSClient在启动时注册了im.message.receive_v1事件监听器来接收消息。准备工作接入前的 3 项准备在开始之前请确认已安装 PromptX 桌面客户端并能正常启动飞书机器人运行在本地机器上客户端需保持运行拥有一个飞书账号并且可以登录飞书开放平台创建企业自建应用电脑可以正常访问互联网长连接是主动外呼不需要对外开放任何端口。第一步在飞书开放平台创建应用并获取 App ID用浏览器登录飞书开放平台进入开发者后台创建一个企业自建应用在应用的凭证与基础信息页面找到并复制两个关键凭证App ID形如cli_xxxxxxxxxxApp Secret点击重置/显示查看这两个凭证就是 PromptX 与飞书之间握手的身份证明请妥善保管不要泄露。 建议给应用起一个容易识别的名字比如PromptX 助手这样在飞书里看到它时会一目了然。第二步为应用添加机器人能力与消息权限在应用功能管理中添加机器人能力——这是接收和发送飞书消息的前提在事件与回调或事件订阅配置中把订阅方式选择为**使用长连接接收事件**即 WebSocket 模式。⚠️ 千万不要选将事件发送至开发者服务器那才需要公网地址开通机器人所需的消息权限通常包括接收群消息/单聊消息、发送消息等im:message相关权限如果配置了事件加密可以顺手记录一下Encrypt Key事件验证密钥后面填入 PromptX可选填最后发布应用版本让配置生效。第三步在 PromptX 桌面端一键完成飞书接入打开 PromptX 桌面客户端进入设置 → 飞书接入该卡片标题为飞书接入说明文字为连接飞书机器人通过飞书消息与 PromptX 交互界面包含三个输入项配置项说明是否必填App ID飞书应用的 App IDcli_开头✅ 必填App Secret飞书应用的 App Secret✅ 必填Encrypt Key事件验证密钥仅配置了事件加密时需要可选操作步骤在设置卡片中填入 App ID 和 App Secret点击**保存配置**点击卡片右上角的开关启动连接状态指示灯变为绿色已连接即表示长连接建立成功到飞书中搜索你的机器人私聊发一句你好或者把机器人拉进群里 它即可开始对话。配置界面代码见 FeishuConfig.tsx。配置保存后会持久化到本地feishu-config.json下次启动 PromptX 时会自动恢复连接无需重复填写——这一逻辑在 FeishuManager.ts 的restore()中实现。消息是如何流动的飞书机器人 × AgentX 智能体接入成功后一条飞书消息在 PromptX 内部经历了这样一段旅程每个聊天窗口一个独立会话FeishuSessionManager.ts 维护飞书 chat_id ↔ 智能体会话的双向映射。你在 A 群的对话记忆不会串到 B 群私聊和群聊各自独立流式生成整条回复FeishuBridge.ts 会累积智能体的流式文本增量text_delta等整轮对话结束conversation_end后再把完整回复一次性发回飞书避免刷屏收到即回执机器人收到你的消息后会先给消息点一个 表情表示已接收随后返回 AI 的正式回答支持发图片你直接发送图片消息机器人会下载图片并作为多模态输入交给智能体理解。连接验证与常见问题排查验证是否接入成功设置页飞书接入卡片显示绿色已连接状态点飞书中给机器人发消息秒回 表情稍后收到智能体的完整文字回复。常见问题现象可能原因与解决启动失败提示 appId/appSecret 为空必填项没填或复制不完整重新粘贴 App ID 与 App Secret启动失败提示 SDK 未安装PromptX 运行环境缺少larksuiteoapi/node-sdk重新安装/更新桌面客户端一直连不上状态不绿检查本机能否访问互联网长连接需要出网权限若公司网络限制出站 WebSocket 端口可换网络测试机器人不回消息确认客户端在前台或后台保持运行飞书端确认事件订阅方式为长连接而非服务器回调回复很慢属于模型生成长度问题长连接本身不会增加延迟FAQ新手最关心的 3 个问题Q1我完全没有服务器可以接入吗可以。这正是长连接模式的价值所在——零服务器、零公网 IP、零端口映射一台能上网的电脑即可。Q2可以同时接入多个飞书群吗可以。每个飞书群或私聊都会在 PromptX 内自动创建独立的智能体会话互不干扰。Q3关掉 PromptX 客户端机器人还能用吗不能。飞书机器人由本地客户端承载客户端运行时机器人才在线再次打开 PromptX 后会自动恢复连接。按照以上步骤操作5 分钟内即可让 PromptX 以飞书机器人的身份住进你的飞书。以后无论是查资料、写文档还是调用智能体能力打开飞书 一下它就行——全程无需公网 IP安全又省心。【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考