接入你的 IM 机器人
用你自己的 FateStar API Key,把紫微斗数接进你自己的机器人:小飞机 Telegram、飞书、LINE 官方账号、微信(个人微信 ClawBot 或公众号)、WhatsApp。群友私聊或 @ 机器人,就能绑生日、排盘、问紫微斗数大模型:郑大钱(英文 ZWDS LLM · ZDQ)。排盘免费,解读费用从你的账号扣。
本套件 (Docker)
校验字数 · 扣你的积分
.env 填了哪家就开哪家。它只调用 FateStar 正式 API:字数限制、档位、价格、扣点全部由 FateStar 服务器判定;套件不缓存、不复用、不改写任何解读。平台对照
| Telegram | 飞书 / Lark | LINE 官方账号 | 个人微信 (ClawBot) | 微信公众号 | ||
|---|---|---|---|---|---|---|
| 建机器人 | @BotFather /newbot | 企业自建应用 + 机器人能力 | Messaging API channel | 微信 → 设置 → 插件 → ClawBot,扫码 | 已认证服务号 / 测试号 | Meta 开发者 App + Cloud API |
| 需要公网网址 | 不需要 (polling) | 需要 HTTPS | 需要 HTTPS | 不需要 (长轮询) | 需要 | 需要 HTTPS |
| 群聊 | ✓ (@ 或指令) | ✓ (@机器人) | ✓ (@官方账号) | ✗ 目前只做一对一 | ✗ 只能一对一 | ✗ 本套件只做一对一 |
| 回复 | 直接发送 | 回复消息 API | reply token 免费,超时改 push | 直接发送 | 客服消息 (48 小时内互动过) | 用户来信后 24 小时内直接回 |
| 单条上限 | 4096 字 | 约 150 KB | 5000 字 | 套件按 2000 字切段 | 2048 字节 (约 680 汉字) | 4096 字 |
| 费用 | 免费 | 免费 (需管理员审核发布) | push 计入每月免费额度 | 免费 | 测试号免费;服务号需认证 | 用户发起的服务消息免费 |
| 注意 | 中国大陆无法直连 | 只限本企业 / 团队成员 | 关掉自动回复,否则抢着回 | ClawBot 灰度开放中;换机或久未上线要重扫 | 要加 IP 白名单;订阅号不支持 | 号码不能同时登 WhatsApp App;正式上线需商家验证 |
| 难度 | ★ | ★★★ | ★★ | ★ | ★★★ | ★★★ |
微信首选个人微信 ClawBot(腾讯官方插件,免公众号、免公网网址);账号还没开放 ClawBot 时再用公众号。非官方的个人号协议 / Hook 工具违反微信条款、有封号风险,企业微信群机器人只能发不能收,本套件都不提供。想用这些工具的话,直接调用 解读 API 即可,扣点规则一样。
下载与启动
- 1到 开发者中心 建一把 API Key(
FSFSKey开头)。Key 等于你的积分钱包,不要贴到群里。 - 2下载套件并解压,复制设置档:
| 1 | cd fatestar-im-bots |
| 2 | cp .env.example .env |
| 3 | # 编辑 .env:填 FATESTAR_API_KEY 和你要的平台凭证 |
| 4 | node src/cli.mjs check # 测连线 + 验 Key(都免费,不排盘) |
启动(推荐 Docker,会自动重启,资料存 ./data):
| 1 | docker compose up -d |
| 2 | # 或不用 Docker: |
| 3 | node src/server.mjs |
程序监听 8787 端口,健康检查 GET /healthz;各平台回调路径:/telegram、/feishu、/line、/wechat、/whatsapp(Telegram polling 与个人微信用长轮询,不需要网址)。飞书、LINE、公众号、WhatsApp 需要公网 HTTPS:放到 VPS、Zeabur、Render、Railway、Fly.io(直接用套件里的 Dockerfile),或在家用 cloudflared tunnel --url http://localhost:8787 拿临时网址。
OpenAI 兼容接法
「紫微斗数大模型:郑大钱」也提供 OpenAI 兼容格式(模型 zwds-zdq)。现成的机器人框架、Coze / Dify / n8n,只要把 Base URL 换成 FateStar、Key 换成你的 FSFSKey 就能接上;本套件默认就走这个端点(设 FATESTAR_API_STYLE=reading 可改回旧的解读 API)。扣点规则与官网相同。
| 1 | Base URL : https://www.fatestar.top/api/v1 |
| 2 | API Key : FSFSKey_你的Key |
| 3 | Model : zwds-zdq |
生日放在请求顶层的 birth 字段(year、month、day、hour 为 0–23 钟点、gender,农历加 calendarType: "lunar");没给时服务器会试着从题目文字解析,解析不到就不调用模型、不扣分。只有最后一则用户消息算题目,历史消息不计字数也不扣分。深度思考用模型 zwds-zdq-think,同价。
机器人指令
| 功能 | Telegram | 飞书 / LINE / 微信 | 说明 |
|---|---|---|---|
| 绑生日 | /bind 1990-05-12 14:30 男 | 绑定 1990-05-12 14:30 男 | 农历加「农历」,闰月再加「闰」;24 小时制 |
| 排盘 | /chart | 排盘 | 十二宫主星、四化、格局(免费) |
| 问紫微 | /ask 今年事业运? | 问 今年事业运? | 私聊直接打字也行;群里要 @机器人 |
| 查看 / 删除 | /me /unbind | 我的 解绑 | 删除只删你自己的生日 |
群里机器人只回应 @它、回复它的消息或指令,闲聊不插嘴。回复语言用 BOT_LANG 设定(zh-TW 繁体 / zh 简体 / en 英文,英文版指令一律用 /bind /ask,例如 /bind 1990-05-12 14:30 male)。
小飞机 Telegram(5 分钟)
- 1在 Telegram 找 @BotFather,发
/newbot,取名(建议「紫微斗数大模型:郑大钱」,英文 ZWDS LLM · ZDQ),拿到一串 token。启动时会自动设好指令菜单和介绍文字。 - 2填进
.env:TELEGRAM_BOT_TOKEN=123456:ABC…,然后启动。默认 polling 模式,不需要公网网址,家里电脑也能跑。 - 3私聊机器人发
/bind 1990-05-12 14:30 男,再发/ask 今年事业运?。 - 4拉进群:直接把机器人加进群。默认隐私模式只收得到指令、@机器人、回复机器人的消息——正好是我们要的。
想改用 webhook(部署在公网主机上更省资源):
| 1 | # .env 加一行随机字串 |
| 2 | TELEGRAM_WEBHOOK_SECRET=换成随机英数字 |
| 3 | # 部署后登记网址 |
| 4 | node src/cli.mjs telegram:set-webhook https://你的域名/telegram |
飞书 / Lark
- 1
- 2「凭证与基础信息」复制 App ID、App Secret →
FEISHU_APP_ID、FEISHU_APP_SECRET。 - 3「添加应用能力」→ 添加机器人。
- 4「权限管理」开通:
im:message、im:message.p2p_msg:readonly(读取用户发给机器人的单聊消息)、im:message.group_at_msg:readonly(接收群聊中 @机器人消息)。 - 5「事件与回调 → 加密策略」复制 Verification Token 与 Encrypt Key 填进
.env,先把程序跑起来。 - 6订阅方式选「将事件发送至开发者服务器」,请求地址填
https://你的域名/feishu,保存时飞书会发 challenge,程序会自动通过。 - 7添加事件:接收消息 v2.0(im.message.receive_v1)。
- 8「版本管理与发布」→ 创建版本并申请发布,企业管理员审核通过后,在飞书里搜索机器人私聊,或拉进群 @它。
LINE 官方账号
- 1打开 LINE Developers Console → 建 Provider → 新建 Messaging API channel(会一并建立官方账号)。
- 2Basic settings 复制 Channel secret →
LINE_CHANNEL_SECRET;Messaging API 页签发行 Channel access token (long-lived) →LINE_CHANNEL_ACCESS_TOKEN。 - 3Messaging API 页签 → Webhook URL 填
https://你的域名/line→ Verify → 打开 Use webhook。 - 4LINE Official Account Manager → 回应设定:关闭自动回应讯息与欢迎讯息;要进群就打开「允许加入群组或多人聊天」。
- 5扫 QR code 加好友,私聊直接问;群里 @官方账号再问。
个人微信(ClawBot,推荐)
腾讯官方的 ClawBot 插件让个人微信号当机器人,套件用长轮询收消息,不需要公众号、不需要公网网址。
- 1准备一个专门当机器人的微信号(建议新号,不要用私人号)。
- 2该微信号开通 ClawBot:微信 → 设置 → 插件 → ClawBot(灰度开放中,看不到就是还没开放给这个号,请改用公众号)。
- 3
.env设WECHAT_ILINK=true,执行node src/cli.mjs wechat:login,用机器人微信号打开印出的链接扫码,手机上点「确认」。 - 4启动程序。朋友加这个微信号为好友后私聊即可(目前只支持一对一,群消息会略过)。
| 1 | # Docker 用户扫码登录(凭据存在 ./data) |
| 2 | docker compose run --rm fatestar-bot node src/cli.mjs wechat:login |
| 3 | docker compose up -d |
微信公众号(服务号 / 测试号)
公众号被动回复必须 5 秒内完成,而解读要 10~40 秒,所以套件先回「success」,算好后用客服消息推回去。订阅号没有客服消息权限,不支持。
- 1个人试用:开 公众平台测试号(微信扫码,免费,所有接口可用)。正式使用:已认证服务号。
- 2把 appID、appsecret 填进
WECHAT_APP_ID、WECHAT_APP_SECRET;WECHAT_TOKEN自己取一串英数字。 - 3先启动程序,再到「服务器配置」(测试号叫「接口配置信息」)填 URL
https://你的域名/wechat、Token 同上,消息加解密选明文模式或兼容模式,提交。 - 4服务号要到「基本配置 → IP 白名单」加入服务器出口 IP(否则拿不到 access_token,错误码 40164)。
- 5关注公众号后直接发消息。用户 48 小时内跟公众号互动过,机器人才能推送回复。
WhatsApp(Meta 官方 Cloud API)
本套件直连 Meta 官方 Cloud API。非官方方案(扫 WhatsApp Web 的 whatsapp-web.js、Baileys 等)违反条款、号码可能被永久封,不提供;Twilio、360dialog 等官方代理商也可用,但 API 不同、要另外付代理费。
- 1Meta for Developers → 创建 App(类型选「商业」)→ 添加 WhatsApp 产品,绑定 Meta 商家账号。
- 2WhatsApp → API Setup:复制 Phone number ID →
WHATSAPP_PHONE_NUMBER_ID。测试可用 Meta 送的免费测试号码(只能发给面板里加入的最多 5 个号码)。 - 3令牌:面板里的临时令牌 24 小时过期;正式请在商家设置 → 系统用户生成永久令牌(勾
whatsapp_business_messaging、whatsapp_business_management)→WHATSAPP_ACCESS_TOKEN。 - 4App 设置 → 基本 → 应用密钥 →
WHATSAPP_APP_SECRET;WHATSAPP_VERIFY_TOKEN自己取一串英数字。 - 5先启动程序,再到 WhatsApp → Configuration → Webhook:回调网址
https://你的域名/whatsapp、验证令牌同上 → 验证并保存 → 订阅 messages。 - 6正式上线:加入自己的号码(不能同时登录 WhatsApp App),显示名称建议用「紫微斗数大模型:郑大钱」或 ZWDS LLM · ZDQ,量大时完成商家验证。
保护你的积分
群里多人共用你的一把 Key 时,一定要设上限(写在 .env):
| 设置 | 默认 | 说明 |
|---|---|---|
MAX_ASKS_PER_USER_PER_DAY | 10 | 每位群友每天最多问几题,0 = 不限 |
MAX_ASKS_PER_DAY | 100 | 整台机器人每天最多几题,0 = 不限 |
ALLOWED_CHAT_IDS | 空 | 只允许这些群 / 用户 id(逗号分隔),空 = 所有人 |
SHOW_CREDITS | true | 回答末尾显示本次扣点与你的余额 |
服务器端另有一层:每把 Key 有每日积分上限(默认 100,在 设置 → API / 接入 AI 调整)和每分钟请求上限(默认 60),同一个群友每把 Key 每分钟最多 10 次;平台重送同一则消息时套件带 Idempotency-Key,只扣一次。
套件这一端的计数按北京时间每天归零。每次调用都带 X-End-User-Id(IM 用户 id 加盐哈希,FateStar 看不到原始 id),方便你在开发者中心看用量。
计费规则
机器人的每一次解读都是对 POST /api/v1/chat/completions 的真实调用,费用照 FateStar 规则从 Key 主人的账户扣:解读扣 API 美金余额,一般题 US$0.10、长题 US$0.20(开通后 30 天内美金不够时改扣积分,公式同官网,经 API 每题最少 1 积分);排盘(/chart)免费。字数上限与网站相同;余额不足会直接拒绝,生成失败会退回。机器人回答末尾会写明这次扣的是美金还是积分(详见 积分计费)。
常见问题
机器人说「余额不足」或「积分不足」?
是 Key 主人的 API 美金余额或积分用完了。到 充值页 补充,或等每日免费积分重置。
生日资料存在哪?
存在你自己主机的 data/store.json,只有生日和当天次数,不存任何解读内容;用户发「解绑」就会删掉。
能同时开多个平台吗?
可以。一个程序同时跑五家,.env 填了哪家就开哪家,共用同一组上限。
想改用 Coze / Dify / n8n?
用它们的 OpenAI 兼容模型节点填 Base URL https://www.fatestar.top/api/v1、Key 与模型 zwds-zdq 即可,扣点规则相同;只是绑生日、每人上限、群里 @ 判断要自己做。