zhujiushequn/juliang-qianchuan-auto-ads-v1/feishu-bot-provisioner

煮酒社群投流龙虾：飞书机器人创建与 OpenClaw 绑定技能

目标：把“客户电脑上的 OpenClaw”快速接入一个可用的飞书机器人。

优先方式：客户安装包后直接运行一键安装命令：

node scripts/install-qianchuan-client.js --setup-feishu --install-gateway --open-dashboard

该命令会调用客户工作区的 bin/feishu_oneclick_setup.js，基于飞书官方 registerApp() 扫码创建应用，拿到 App ID/App Secret 后写入客户本机 OpenClaw 配置。只有扫码/授权需要客户本人确认。

核心原则：不能绕过人工确认，但要尽量替客户打开页面、定位入口、告诉客户每一步填什么。

品牌与归属标识

本技能属于 煮酒社群投流龙虾 自动化体系。

在客户可见的位置，优先使用以下命名：

• 应用名称：煮酒社群投流龙虾
• 机器人名称：煮酒社群投流龙虾
• 描述：煮酒社群出品，用于巨量千川直播加热自动化通知与交互

所有生成的 SOP、初始化提示、配置说明、监控汇报中，应尽量保留 煮酒社群投流龙虾 字样，用于标识来源与归属。

注意：品牌字样只能增加归属识别，不能替代真正的授权、许可证、账号隔离和代码保护。

边界

可以做：

• 打开飞书开放平台网页
• 辅助客户登录后继续操作
• 按页面中文文案引导客户创建应用
• 告诉客户应用名称、描述、机器人名称怎么填
• 引导客户开启机器人能力
• 告诉客户事件订阅 URL、Verification Token、Encrypt Key 填在哪里
• 告诉客户需要勾选哪些事件和权限
• 收集 App ID / App Secret（一键自动）+ Verification Token / Encrypt Key（readline 提示客户从开放平台复制粘贴，可跳过）
• 在用户确认后写入 OpenClaw 本地配置或客户工作区配置
• 测试飞书消息收发
• 记录客户 open_id / chat_id，供后续主动通知使用

不能做：

• 绕过登录、二维码、验证码
• 绕过组织管理员审批
• 替客户确认授权/发布/安装应用
• 在公开文档里保存 App Secret、Encrypt Key 等敏感信息

遇到人工节点时，不要结束流程；要明确告诉客户：

1. 当前卡在哪一步
2. 他需要点哪里/填什么/确认什么
3. 完成后回复“好了”或“继续”

推荐交付模式

采用“网页辅助 + 对话向导”：

如果一键创建失败或客户不愿扫码授权，再退回到此模式：

1. 助手打开飞书开放平台。
2. 如果出现登录/二维码/验证码，暂停并让客户处理。
3. 登录后，助手继续引导点击入口。
4. 到需要客户填写/确认的位置，直接给出可复制内容。
5. 客户复制 App ID/Secret 等回填。
6. 助手写入 OpenClaw 配置并测试。

初始化信息

需要收集或生成：

feishu:
  app_name: 煮酒社群投流龙虾
  app_description: 煮酒社群出品，用于巨量千川直播加热自动化通知与交互
  bot_name: 煮酒社群投流龙虾
  app_id: cli_xxx
  app_secret: xxx
  verification_token: xxx
  encrypt_key: xxx
  event_subscribe_url: https://xxx/webhook/feishu
  owner_open_id: ou_xxx
  target_chat: current | user:ou_xxx | chat:oc_xxx

敏感字段只写入本地安全配置，不写入 README、SOP、MEMORY 等公开文档。

详细创建向导

1. 打开飞书开放平台

打开：

https://open.feishu.cn/app

如果出现登录、二维码、验证码：

• 暂停
• 告诉客户完成登录
• 客户回复“好了”后继续

2. 创建企业自建应用

登录后按页面中文文案操作。通常路径：

1. 点击 创建应用
2. 选择 企业自建应用
3. 应用名称填写：煮酒社群投流龙虾
4. 应用描述填写：煮酒社群出品，用于巨量千川直播加热自动化通知与交互
5. 点击创建/确定

如果页面出现组织选择、管理员审批、协议确认：暂停让客户处理。

3. 获取 App ID / App Secret

进入应用后台后，通常在 凭证与基础信息 或 应用凭证 页面。

让客户复制：

• App ID
• App Secret

提示：

• App Secret 属于敏感信息，只用于本机 OpenClaw 配置。
• 不要发到群里，不要写进公开文档。

4. 开启机器人能力

在应用后台：

1. 找到 应用能力
2. 点击 机器人
3. 点击 启用机器人
4. 机器人名称填写：煮酒社群投流龙虾
5. 头像可选
6. 保存

需要客户人工点击启用/保存时，明确告诉客户点哪个按钮。

5. 配置事件订阅

进入 事件订阅。

需要填写：

请求地址: <OpenClaw Gateway 暴露的 Feishu webhook/event URL>
Verification Token: <客户在飞书开放平台「事件订阅」生成；一键安装时 readline 提示复制粘贴；也可手动写入 .env.feishu 的 FEISHU_VERIFICATION_TOKEN>
Encrypt Key: <客户在飞书开放平台「事件订阅」生成（可选）；一键安装时 readline 提示复制粘贴；也可手动写入 .env.feishu 的 FEISHU_ENCRYPT_KEY>

如果当前还没有公网 URL，应告诉客户需要以下其中一种：

• OpenClaw 已配置公网回调地址
• 使用内网穿透/反向代理
• 使用 OpenClaw 提供的 Gateway/Channel 回调地址

URL 校验失败时，不要乱试；先检查：

• OpenClaw Gateway 是否运行
• 回调 URL 是否公网可访问
• Token / Encrypt Key 是否一致
• 飞书事件订阅是否要求 HTTPS

6. 订阅事件

至少订阅消息事件。页面文案可能变化，以飞书当前中文为准。

建议订阅：

• 接收消息 / 消息接收
• 接收私聊消息
• 如需要群里使用，再订阅 接收群聊消息

如果飞书页面按事件类型展示，可搜索关键词：

消息
im.message
receive message

只勾选必要事件，不开无关事件。

7. 配置权限

进入 权限管理。

最小权限建议：

• 发送消息
• 接收消息
• 获取用户 open_id / 用户基本信息
• 获取群信息（仅当需要群聊）

如果千川技能不需要飞书文档/表格，不要开文档、表格、通讯录高级权限。

权限申请后，如果需要发布版本或管理员审批，暂停让客户处理。

8. 发布/安装应用

如果页面要求：

• 版本管理
• 创建版本
• 发布
• 安装应用
• 管理员审核

则告诉客户按页面完成。

不要代替客户确认组织级授权。

9. 写入 OpenClaw 配置

客户提供 App ID / App Secret / Token 后：

1. 写入本地 OpenClaw 配置或环境变量。
2. 不写入公开文档。
3. 绑定当前客户 agent/channel。
4. 记录非敏感字段到客户工作区，例如 bot_name、app_id、owner_open_id。

10. 测试收发消息

测试步骤：

1. 让客户给机器人发：测试
2. 确认 OpenClaw 收到消息
3. 回复：飞书机器人已绑定成功
4. 记录当前会话 target：user:ou_xxx 或 chat:oc_xxx
5. 测试一次主动通知：绑定测试完成

对客户说话模板

登录暂停

我已打开飞书开放平台，现在需要你完成登录/扫码。完成后回复“好了”，我继续配置。

创建应用填写

这里请填写：
应用名称：煮酒社群投流龙虾
应用描述：煮酒社群出品，用于巨量千川直播加热自动化通知与交互
填好后点“创建”。

开启机器人

现在进入「应用能力 > 机器人」，请点击“启用机器人”。
机器人名称填：煮酒社群投流龙虾。
保存后回复“好了”。

事件订阅

这里需要填事件订阅地址。我会给你 URL、Verification Token 和 Encrypt Key。
填好后点“保存/校验”。如果校验失败，把页面错误发我。

权限配置

权限只开最小集合：发送消息、接收消息、获取用户 open_id。如果要在群里使用，再加获取群信息。不要开无关权限。

完成测试

现在请给机器人发“测试”。如果我能收到并回复，就说明绑定成功。

开源与品牌署名

煮酒社群投流龙虾 计划按开源方式交付。默认不设置授权码、到期控制或远程授权校验。

保留要求：

• 项目名称、SOP、机器人推荐名称中保留 煮酒社群投流龙虾 字样。
• README / SOP 中保留 煮酒社群出品 或等价署名。
• 不把 App Secret、Encrypt Key、客户账号信息写入公开仓库。
• 开源仓库只放模板、SOP、技能说明和初始化脚本；客户私密配置放本地 .env 或 customer-config.local.yaml。

与千川技能的衔接

飞书绑定成功后，写入客户工作区：

feishu:
  enabled: true
  target: current
  owner_open_id: ou_xxx
  bot_name: 煮酒社群投流龙虾

然后千川直播加热技能继续初始化：

• 千川账户
• 抖音号
• 预算
• 出价
• 人群画像
• 直播时间
• 本地计划台账 memory/qianchuan-plan-registry.json
• 监控状态校验 qc_monitor_state_validate.js
• 删除策略 monitor.delete_mode
• 口令 开始直播了

衔接后先运行客户工作区预检：

bash bin/qianchuan_preflight.sh

预检未通过时，不要创建计划、发布、调价或删除。

验收标准

绑定完成必须满足：

• 客户能向飞书机器人发送消息
• OpenClaw 能收到消息
• OpenClaw 能回复当前会话
• 后台任务能向该会话主动通知
• 已记录 owner_open_id 或 chat_id
• App Secret / Encrypt Key 未写入公开文档

停止条件

遇到以下情况暂停并给出明确下一步：

• 飞书登录
• 二维码/验证码
• 组织管理员审批
• 权限授权确认
• 事件订阅 URL 校验失败且无法判断原因
• 客户不清楚 App Secret/Encrypt Key 是否可以提供

暂停时说明具体动作，不要只说“我不能处理”。