创建与管理

机器人的创建和管理可以在 Web 的「设置 → 自动化机器人」完成；如果你要在脚本或 AI 编程助手里批量操作，也可以使用官方命令行工具 2s1。

Web 路径会在创建成功后直接引导你生成运行密钥，并给出发布测试 Bubble 的命令。机器人的头像、昵称、简介也都在这里改——它是一个拥有独立资料页和账号身份的自动化账号（默认可见性为 private）。

安装与登录

npm install -g @2someone/cli

# 登录（会打开浏览器完成授权）
2s1 login

# 确认登录状态
2s1 whoami

创建机器人

2s1 bot create --username my_bot --nickname "我的机器人" \
  --description "这是一个示例机器人" \
  --capability bubble.create --capability bubble.read

创建成功后会返回 botUserId，后续管理命令都用它来指定机器人。

Web「设置 → 自动化机器人」和直接调用 POST /api/v1/bots 时，省略 capabilities 也使用同一组默认能力：bubble.create + chat.send。Web 创建弹窗预选的也是这两项；CLI 示例若显式传入能力，则以你传入的列表为准（它是替换，不是追加）。

两把密钥，别混用

机器人体系有两种密钥，用途完全不同：

管理运行密钥

# 列出当前密钥
2s1 bot key list <botUserId>

# 轮换：生成新密钥，同时自动禁用旧密钥
2s1 bot key rotate <botUserId> --yes

# 轮换并直接打印环境变量写法，方便复制进部署平台
2s1 bot key rotate <botUserId> --print-env --yes

# 生成一把有有效期的临时密钥（如调试用，3600 秒后失效）
2s1 bot key rotate <botUserId> --expires-in 3600 --yes

# 吊销指定密钥
2s1 bot key revoke <botUserId> <keyId> --yes

每个机器人同一时间只有一把启用的运行密钥——轮换即作废旧钥，记得同步更新部署环境里的 Secret。--expires-in 支持 3600 秒到 1 年；不带则密钥长期有效。新轮换的密钥自动带 events.read，用来拉 webhook 同一份事件 feed；这不是群安装授权。

管理机器人状态

2s1 bot list                      # 列出我创建的机器人
2s1 bot show <botUserId>          # 查看详情
2s1 bot update <botUserId> --nickname "新昵称"   # 修改资料
2s1 bot pause <botUserId>         # 暂停（接口调用会被拒绝）
2s1 bot resume <botUserId>        # 恢复
2s1 bot disable <botUserId> --yes # 停用账号

2s1 bot update 能改的不止昵称，下面这些字段都可以更新：

机器人头像目前在 Web「设置 → 自动化机器人」里上传——进入对应机器人即可换头像、改昵称和简介，让它更像一个独立账号。

安装到群聊

机器人要在群聊里发消息或管理自己的 reaction，必须先被安装到那个群。当前安装会创建该群的 Bot 授权快照，因此安装操作必须由目标群主或管理员发起；Bot 的 installPolicy 还会叠加机器人所有者限制：

2s1 bot install <conversationId> --bot @my_bot --yes

--bot 既可以填 @username，也可以填 botUserId。如果直接调安装接口（POST /api/v1/chat/conversations/<id>/bots），至少传其中一个（通常只传一个）即可。安装者仍须是群成员且具备邀请权限；群已满时会返回 HTTP 400 和群已满提示。常见安装拒绝 reason 包括：bot_not_found（账号不存在；用 botUserId 指向非机器人账号时也会归入此项）、not_a_bot（按用户名查到的账号不是机器人）、bot_inactive（机器人已暂停/停用）、bot_install_blocked（安装策略不允许）、bot_missing_chat_capability（没有 chat.send、chat.read 或 chat.react 中任何一项）、ai_character_group_not_supported（AI 角色不能进群）。重复安装或非法参数会返回 400；群不存在、不是群聊或你不是成员会返回 404。group_full 是服务端内部错误码，当前安装接口不保证把它作为稳定 reason 返回。

public 只表示不再要求安装者是机器人创建者/拥有者，但不能绕过目标群的 owner/admin consent；owner_only 和当前尚未细分名单的 invite_required 还会要求安装者是机器人创建者/拥有者。无论哪种 Bot 安装策略，安装者都必须是目标群的 active 成员，并由目标群主或管理员发起授权；群的 inviteRolePolicy 不会把普通成员升级为 Bot grant approver。这两层策略彼此独立。安装成功时会把当时的 defaultPrivacyMode 复制到这次安装，之后修改机器人默认隐私模式不会改变既有安装；要应用新模式，请先在群成员管理中移除机器人，再重新安装。公开 API 目前没有单独的 Bot uninstall 或安装级隐私模式调整入口。

登记 HTTPS 回调

反应型机器人被斜杠命令点到时，平台会向主人登记的公开 HTTPS 地址发送签名 POST。群安装界面没有 Webhook 勾选，地址只对主人可见。Mobile 暂无该设置，请用 Web 或 CLI：

2s1 bot endpoint create <botUserId> --url https://example.com/bot/events --yes
2s1 bot endpoint show <botUserId>
2s1 bot endpoint pause <botUserId> --yes

对端必须先通过 endpoint.verify challenge（2xx 且回显同一个 challenge），回调才会变成 active。暂停后事件仍可用 runtime key 从 feed 补拉。步骤、验签和限额见 Webhook 与轮询。

测试机器人

CLI 内置了端到端测试命令，用运行密钥真实调用接口：

# 读取机器人自己发过的泡泡（只读，安全）
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test bubble-read

# 真实发布一条泡泡
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test bubble-create --text "Hello, 泡泡!" --yes

# 向群聊发一条真实消息
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test chat-send <conversationId> --text "在呢" --yes

# 按安装隐私模式读取群聊（轮询保底；拉消息限额按主人 VIP）
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test chat-read <conversationId> --limit 20

# 拉取 inbound 事件 feed（webhook 丢失时补拉）
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test events --limit 20

所有命令都支持 --json 输出，方便脚本和 AI 编程助手使用。