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

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

【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 ｜ PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX

PromptX 是一款领先的 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 项准备

在开始之前，请确认：

1. 已安装 PromptX 桌面客户端并能正常启动（飞书机器人运行在本地机器上，客户端需保持运行）；
2. 拥有一个飞书账号，并且可以登录飞书开放平台创建企业自建应用；
3. 电脑可以正常访问互联网（长连接是主动外呼，不需要对外开放任何端口）。

第一步：在飞书开放平台创建应用并获取 App ID

1. 用浏览器登录飞书开放平台，进入"开发者后台"，创建一个企业自建应用；
2. 在应用的"凭证与基础信息"页面，找到并复制两个关键凭证：
   • App ID（形如cli_xxxxxxxxxx）
   • App Secret（点击"重置/显示"查看）

这两个凭证就是 PromptX 与飞书之间"握手"的身份证明，请妥善保管，不要泄露。

💡 建议给应用起一个容易识别的名字，比如"PromptX 助手"，这样在飞书里看到它时会一目了然。

第二步：为应用添加机器人能力与消息权限

1. 在应用功能管理中，添加"机器人"能力——这是接收和发送飞书消息的前提；
2. 在"事件与回调"（或"事件订阅"）配置中，把订阅方式选择为**"使用长连接接收事件"**（即 WebSocket 模式）。⚠️ 千万不要选"将事件发送至开发者服务器"，那才需要公网地址；
3. 开通机器人所需的消息权限，通常包括：接收群消息/单聊消息、发送消息等im:message相关权限；
4. 如果配置了事件加密，可以顺手记录一下Encrypt Key（事件验证密钥），后面填入 PromptX（可选填）；
5. 最后发布应用版本，让配置生效。

第三步：在 PromptX 桌面端一键完成飞书接入

打开 PromptX 桌面客户端，进入设置 → 飞书接入（该卡片标题为"飞书接入"，说明文字为"连接飞书机器人，通过飞书消息与 PromptX 交互"），界面包含三个输入项：

操作步骤：

1. 在设置卡片中填入 App ID 和 App Secret，点击**"保存配置"**；
2. 点击卡片右上角的开关启动连接，状态指示灯变为绿色"已连接"即表示长连接建立成功；
3. 到飞书中搜索你的机器人，私聊发一句"你好"，或者把机器人拉进群里 @ 它，即可开始对话。

配置界面代码见 FeishuConfig.tsx。配置保存后会持久化到本地feishu-config.json，下次启动 PromptX 时会自动恢复连接，无需重复填写——这一逻辑在 FeishuManager.ts 的restore()中实现。

消息是如何流动的：飞书机器人 × AgentX 智能体

接入成功后，一条飞书消息在 PromptX 内部经历了这样一段旅程：

• 每个聊天窗口一个独立会话：FeishuSessionManager.ts 维护"飞书 chat_id ↔ 智能体会话"的双向映射。你在 A 群的对话记忆不会串到 B 群，私聊和群聊各自独立；
• 流式生成，整条回复：FeishuBridge.ts 会累积智能体的流式文本增量（text_delta），等整轮对话结束（conversation_end）后再把完整回复一次性发回飞书，避免刷屏；
• 收到即回执：机器人收到你的消息后会先给消息点一个 👍 表情，表示已接收，随后返回 AI 的正式回答；
• 支持发图片：你直接发送图片消息，机器人会下载图片并作为多模态输入交给智能体理解。

连接验证与常见问题排查

验证是否接入成功：

1. 设置页飞书接入卡片显示绿色"已连接"状态点；
2. 飞书中给机器人发消息，秒回 👍 表情；
3. 稍后收到智能体的完整文字回复。

常见问题：

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