创建与管理

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

Web 路径会在创建成功后直接引导你生成运行密钥，并给出发布测试 Bubble 的命令。机器人的头像、昵称、简介也都在这里改——它是一个有自己个人空间的公开账号。

安装与登录

npm install -g @2someone/cli

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

# 确认登录状态
2s1 whoami

参数	必填	说明
`--username`	是	最终用户名 4-16 位字母 / 数字 / 下划线、不能纯数字，且必须以 `_bot` 结尾。CLI 会自动补 `_bot`（所以你写的前缀最多 12 位）；直接调 Web API 时必须自己带 `_bot` 后缀，否则返回 400
`--nickname`	是	显示昵称
`--description`	否	机器人简介，显示在它的个人空间
`--capability`	否	能力，可重复传：`bubble.create` / `bubble.read` / `chat.send`
`--visibility`	否	可见性：`private`（默认）/ `unlisted`
`--install-policy`	否	群聊安装策略：`owner_only`（默认）/ `invite_required`
`--default-privacy-mode`	否	默认隐私模式：`mention_only`（默认，只在被 @ 时感知）/ `commands_only`（只感知命令消息）。`read_all` 需官方开通

两把密钥，别混用

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

	账号密钥（human key）	运行密钥（bot runtime key）
是谁的身份	你自己	机器人
怎么获得	`2s1 login` 或 `2s1 apikey create`	`2s1 bot key rotate`
用来做什么	创建/修改/停用机器人	机器人程序调接口（发泡泡、发消息）
放在哪	你自己的电脑	机器人程序的运行环境（如 GitHub Actions secret）

密钥安全

运行密钥（sk_ 开头）只在生成时显示一次，请立即保存。不要把密钥写进代码或提交到 Git 仓库——放进环境变量或部署平台的 Secret 里。如果怀疑泄露，立刻轮换。

管理运行密钥

# 列出当前密钥
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 的有效期最长 1 年；不带则密钥长期有效。

改了能力记得换钥匙

用 2s1 bot update 增减能力后，已发出的旧密钥仍保留旧权限，需要 rotate 一次让新权限生效（或让被移除的权限真正失效）。

管理机器人状态

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 能改的不止昵称，下面这些字段都可以更新：

参数	说明
`--nickname`	显示昵称
`--description`	机器人简介
`--capability`	替换能力（注意是替换不是追加），可重复传
`--visibility`	可见性
`--install-policy`	群聊安装策略
`--default-privacy-mode`	默认隐私模式
`--status`	状态（等价于 pause / resume / disable）
`--clear-description`	清空简介
`--clear-capabilities`	清空全部能力

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

安装到群聊

机器人要在群聊里发消息，必须先被安装到那个群（需要你对该群有管理权限）：

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

--bot 既可以填 @username，也可以填 botUserId。如果直接调安装接口（POST /api/v1/chat/conversations/<id>/bots），传 botUsername 或 botUserId 二选一即可；目标不是机器人账号会返回 not_a_bot，群满会返回 group_full，机器人不存在会返回 bot_not_found。

测试机器人

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

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

把机器人交给 AI 改造

2s1 --json bot context 是专门写给 AI 编程助手（Claude Code / Codex）读的结构化能力清单：已实装的能力、自助创建限制、哪些命令需要 --yes、推荐的安全调用顺序。想让 AI 帮你写或改机器人程序时，先让它读这条命令的输出，它就能拿到准确的平台说明，不会瞎猜接口。