Bot 开发指南
Bot 是一个普通的用户行,只是带了三个标记:
| 字段 | 值 | 含义 |
|---|---|---|
users.is_bot |
TRUE |
机器人标记,客户端在名字旁显示徽章 |
users.bot_owner_id |
创建者(人类)的 user id | 归属关系,随所有者删除而级联删除 |
users.password_hash |
24 字节随机数 | 永远匹配不上任何密码,因此 bot 无法交互式登录 |
此外它的 role='user'、needs_registration=FALSE,创建时自动加入内置默认组「所有人」。
由此推出三条重要结论:
- Bot 在系统各处都表现为正常用户——发帖、发消息、进群、加营地,署名都是它自己(自己的昵称、头像、徽章)。
- Bot 没有额外能力,也没有额外限制:服务端没有任何一处对
is_bot做接口级拦截,唯一例外是 bot 不能再创建 bot。 - Bot 的权限完全取决于它所在的用户组;新建 bot 落在默认组,拿到的是「普通注册用户」那套权限。
认证方式是静态 API token(ofb_ 前缀),不是账号密码,也不是有时效的 JWT。Token 与 bot 一一对应(bot_tokens.user_id 是主键),重置即旧 token 立即失效。
设服务端地址为 $BASE(本地默认 http://localhost:8080,线上通常是 HTTPS 域名),所有接口都在网关的 /api/v1 之下。
1. 用人类账号创建 bot
Section titled “1. 用人类账号创建 bot”创建用的是你自己的登录凭据(JWT,或你自己的 bot token 也行),不是新 bot 的 token:
curl -s -X POST "$BASE/api/v1/bots" \ -H "Authorization: Bearer $MY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"username":"weather_watcher","nickname":"天气预报"}'{ "user": { "id": 4242, "username": "weather_watcher", "nickname": "天气预报", "is_bot": true, "bot_owner_id": 7, "created_at": "2026-10-10T15:20:12Z" }, "token": "ofb_9f2c…(64 位十六进制)"}也可以从客户端 App 创建:账号页 →「我的机器人」→「新建」。
2. 验证 token
Section titled “2. 验证 token”export BOT_TOKEN="ofb_9f2c…"curl -s "$BASE/api/v1/users/me" -H "Authorization: Bearer $BOT_TOKEN"返回的 id 就是 4242——bot 以自己身份行动:X-User-ID 由网关按 token 解析,下游服务看到的是 bot 自己的 id,不是创建者的。
3. 发一条帖子
Section titled “3. 发一条帖子”curl -s -X POST "$BASE/api/v1/posts" \ -H "Authorization: Bearer $BOT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"content":"今天北京 21°C,晴。","visibility":"public"}'201 + 帖子对象本身。
4. 发一条聊天消息
Section titled “4. 发一条聊天消息”curl -s "$BASE/api/v1/conversations" -H "Authorization: Bearer $BOT_TOKEN" # 找会话 id
curl -s -X POST "$BASE/api/v1/conversations/$CONV_ID/messages" \ -H "Authorization: Bearer $BOT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"content":"收到,我来处理。"}'Authorization: Bearer ofb_<64 位小写十六进制>Token 固定为 ofb_ + 32 字节随机数的十六进制(共 68 个字符)。前缀 ofb_ 是网关识别 bot token 的唯一依据——看到它就这走 bot 解析路径,否则按 JWT 解析。
网关做了什么
Section titled “网关做了什么”- 取
Authorization头,剥掉Bearer; - 以
ofb_开头 → 按 token 哈希查bot_tokens并JOIN users校验is_bot; - 命中则返回 bot 的 user id,并顺带更新
last_used_at(best-effort,失败不影响请求); - 设置内部头
X-User-ID: <bot id>后转发;客户端自己伪造的X-User-ID会被覆盖或删除,无法冒充他人。
哪些路由认 bot token
Section titled “哪些路由认 bot token”| 路由级别 | 是否认 |
|---|---|
authPublic |
✅ 认,且会让返回“个性化”(如自己的点赞状态) |
authRequired |
✅ 认 |
authPermission |
✅ 认,权限按 bot 所在组判定 |
authTicket(GET /ws) |
身份头被删除,只认一次性票据 |
GET /api/v1/files/... |
❌ 不认 |
失败长什么样
Section titled “失败长什么样”| 情况 | 响应 |
|---|---|
没有 Authorization 头 |
401 {"error":"missing authorization token"} |
| token 被重置 / 不存在 / bot 被封禁 | 401 {"error":"invalid bot token"} |
| 有 token 但缺该接口所需权限 | 403 {"error":"permission denied","permission":"<权限键>"} |