开发者文档 / 接入你的 IM 机器人

接入你的 IM 机器人

用你自己的 FateStar API Key,把紫微斗数接进你自己的机器人:小飞机 Telegram、飞书、LINE 官方账号、微信(个人微信 ClawBot 或公众号)、WhatsApp。群友私聊或 @ 机器人,就能绑生日、排盘、问紫微斗数大模型:郑大钱(英文 ZWDS LLM · ZDQ)。排盘免费,解读费用从你的账号扣。

群友私聊 / @机器人
→
Telegram · 飞书 · LINE · 微信 · WhatsApp
→
你的机器人
本套件 (Docker)
→
紫微斗数大模型:郑大钱
校验字数 · 扣你的积分
套件零依赖 (Node.js 20+ 或 Docker),一个程序同时跑五家,.env 填了哪家就开哪家。它只调用 FateStar 正式 API:字数限制、档位、价格、扣点全部由 FateStar 服务器判定;套件不缓存、不复用、不改写任何解读。

平台对照

Telegram飞书 / LarkLINE 官方账号个人微信 (ClawBot)微信公众号WhatsApp
建机器人@BotFather /newbot企业自建应用 + 机器人能力Messaging API channel微信 → 设置 → 插件 → ClawBot,扫码已认证服务号 / 测试号Meta 开发者 App + Cloud API
需要公网网址不需要 (polling)需要 HTTPS需要 HTTPS不需要 (长轮询)需要需要 HTTPS
群聊✓ (@ 或指令)✓ (@机器人)✓ (@官方账号)✗ 目前只做一对一✗ 只能一对一✗ 本套件只做一对一
回复直接发送回复消息 APIreply token 免费,超时改 push直接发送客服消息 (48 小时内互动过)用户来信后 24 小时内直接回
单条上限4096 字约 150 KB5000 字套件按 2000 字切段2048 字节 (约 680 汉字)4096 字
费用免费免费 (需管理员审核发布)push 计入每月免费额度免费测试号免费;服务号需认证用户发起的服务消息免费
注意中国大陆无法直连只限本企业 / 团队成员关掉自动回复,否则抢着回ClawBot 灰度开放中;换机或久未上线要重扫要加 IP 白名单;订阅号不支持号码不能同时登 WhatsApp App;正式上线需商家验证
难度★★★★★★★★★★★★★

微信首选个人微信 ClawBot(腾讯官方插件,免公众号、免公网网址);账号还没开放 ClawBot 时再用公众号。非官方的个人号协议 / Hook 工具违反微信条款、有封号风险,企业微信群机器人只能发不能收,本套件都不提供。想用这些工具的话,直接调用 解读 API 即可,扣点规则一样。

下载与启动

  1. 1
    到 开发者中心 建一把 API Key(FSFSKey 开头)。Key 等于你的积分钱包,不要贴到群里。
  2. 2
    下载套件并解压,复制设置档:
bash
1cd fatestar-im-bots
2cp .env.example .env
3# 编辑 .env:填 FATESTAR_API_KEY 和你要的平台凭证
4node src/cli.mjs check # 测连线 + 验 Key(都免费,不排盘)

启动(推荐 Docker,会自动重启,资料存 ./data):

bash
1docker compose up -d
2# 或不用 Docker:
3node 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)。扣点规则与官网相同。

bash
1Base URL : https://www.fatestar.top/api/v1
2API Key : FSFSKey_你的Key
3Model : 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. 1
    在 Telegram 找 @BotFather,发 /newbot,取名(建议「紫微斗数大模型:郑大钱」,英文 ZWDS LLM · ZDQ),拿到一串 token。启动时会自动设好指令菜单和介绍文字。
  2. 2
    填进 .env:TELEGRAM_BOT_TOKEN=123456:ABC…,然后启动。默认 polling 模式,不需要公网网址,家里电脑也能跑。
  3. 3
    私聊机器人发 /bind 1990-05-12 14:30 男,再发 /ask 今年事业运?。
  4. 4
    拉进群:直接把机器人加进群。默认隐私模式只收得到指令、@机器人、回复机器人的消息——正好是我们要的。

想改用 webhook(部署在公网主机上更省资源):

bash
1# .env 加一行随机字串
2TELEGRAM_WEBHOOK_SECRET=换成随机英数字
3# 部署后登记网址
4node src/cli.mjs telegram:set-webhook https://你的域名/telegram

飞书 / Lark

  1. 1
    打开 飞书开放平台(Lark 用 open.larksuite.com,并把 FEISHU_DOMAIN 改成 https://open.larksuite.com)→ 创建企业自建应用。
  2. 2
    「凭证与基础信息」复制 App ID、App Secret → FEISHU_APP_ID、FEISHU_APP_SECRET。
  3. 3
    「添加应用能力」→ 添加机器人。
  4. 4
    「权限管理」开通:im:message、im:message.p2p_msg:readonly(读取用户发给机器人的单聊消息)、im:message.group_at_msg:readonly(接收群聊中 @机器人消息)。
  5. 5
    「事件与回调 → 加密策略」复制 Verification Token 与 Encrypt Key 填进 .env,先把程序跑起来。
  6. 6
    订阅方式选「将事件发送至开发者服务器」,请求地址填 https://你的域名/feishu,保存时飞书会发 challenge,程序会自动通过。
  7. 7
    添加事件:接收消息 v2.0(im.message.receive_v1)。
  8. 8
    「版本管理与发布」→ 创建版本并申请发布,企业管理员审核通过后,在飞书里搜索机器人私聊,或拉进群 @它。
为了防止别人伪造事件来花你的积分,套件要求至少设置 Verification Token 或 Encrypt Key(建议两个都设),否则拒绝启动。

LINE 官方账号

  1. 1
    打开 LINE Developers Console → 建 Provider → 新建 Messaging API channel(会一并建立官方账号)。
  2. 2
    Basic settings 复制 Channel secret → LINE_CHANNEL_SECRET;Messaging API 页签发行 Channel access token (long-lived) → LINE_CHANNEL_ACCESS_TOKEN。
  3. 3
    Messaging API 页签 → Webhook URL 填 https://你的域名/line → Verify → 打开 Use webhook。
  4. 4
    LINE Official Account Manager → 回应设定:关闭自动回应讯息与欢迎讯息;要进群就打开「允许加入群组或多人聊天」。
  5. 5
    扫 QR code 加好友,私聊直接问;群里 @官方账号再问。
回复优先用 reply token(免费)。解读超过 50 秒才改用 push,push 会计入官方账号每月的免费消息额度。

微信公众号(服务号 / 测试号)

公众号被动回复必须 5 秒内完成,而解读要 10~40 秒,所以套件先回「success」,算好后用客服消息推回去。订阅号没有客服消息权限,不支持。

  1. 1
    个人试用:开 公众平台测试号(微信扫码,免费,所有接口可用)。正式使用:已认证服务号。
  2. 2
    把 appID、appsecret 填进 WECHAT_APP_ID、WECHAT_APP_SECRET;WECHAT_TOKEN 自己取一串英数字。
  3. 3
    先启动程序,再到「服务器配置」(测试号叫「接口配置信息」)填 URL https://你的域名/wechat、Token 同上,消息加解密选明文模式或兼容模式,提交。
  4. 4
    服务号要到「基本配置 → IP 白名单」加入服务器出口 IP(否则拿不到 access_token,错误码 40164)。
  5. 5
    关注公众号后直接发消息。用户 48 小时内跟公众号互动过,机器人才能推送回复。

WhatsApp(Meta 官方 Cloud API)

本套件直连 Meta 官方 Cloud API。非官方方案(扫 WhatsApp Web 的 whatsapp-web.js、Baileys 等)违反条款、号码可能被永久封,不提供;Twilio、360dialog 等官方代理商也可用,但 API 不同、要另外付代理费。

  1. 1
    Meta for Developers → 创建 App(类型选「商业」)→ 添加 WhatsApp 产品,绑定 Meta 商家账号。
  2. 2
    WhatsApp → API Setup:复制 Phone number ID → WHATSAPP_PHONE_NUMBER_ID。测试可用 Meta 送的免费测试号码(只能发给面板里加入的最多 5 个号码)。
  3. 3
    令牌:面板里的临时令牌 24 小时过期;正式请在商家设置 → 系统用户生成永久令牌(勾 whatsapp_business_messaging、whatsapp_business_management)→ WHATSAPP_ACCESS_TOKEN。
  4. 4
    App 设置 → 基本 → 应用密钥 → WHATSAPP_APP_SECRET;WHATSAPP_VERIFY_TOKEN 自己取一串英数字。
  5. 5
    先启动程序,再到 WhatsApp → Configuration → Webhook:回调网址 https://你的域名/whatsapp、验证令牌同上 → 验证并保存 → 订阅 messages。
  6. 6
    正式上线:加入自己的号码(不能同时登录 WhatsApp App),显示名称建议用「紫微斗数大模型:郑大钱」或 ZWDS LLM · ZDQ,量大时完成商家验证。
用户先发消息后 24 小时内,机器人可以自由回复,这类服务消息 Meta 不收费;机器人不会主动推播。

保护你的积分

群里多人共用你的一把 Key 时,一定要设上限(写在 .env):

设置默认说明
MAX_ASKS_PER_USER_PER_DAY10每位群友每天最多问几题,0 = 不限
MAX_ASKS_PER_DAY100整台机器人每天最多几题,0 = 不限
ALLOWED_CHAT_IDS空只允许这些群 / 用户 id(逗号分隔),空 = 所有人
SHOW_CREDITStrue回答末尾显示本次扣点与你的余额

服务器端另有一层:每把 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 即可,扣点规则相同;只是绑生日、每人上限、群里 @ 判断要自己做。