catbus/docs/guide/login.md

登录

各平台的 web 端不登录几乎看不到内容，所以 catbus 在 web 端除 auth 以外的命令都需要登录。未登录时命令报 AUTH_REQUIRED（退出码 3），hint 里就是该执行的登录命令。

catbus <platform> auth login [-a <账号名>] [--method qrcode|sms|password|cookie] [--scope <子站点>]

规范见 AGENTS.md 5.2、5.3。

各平台支持的方式

平台	扫码	短信	账密	cookie	默认
xhs	✓	✓		✓	qrcode
douyin	✓	✓		✓	qrcode
tiktok				✓	cookie
bilibili	✓	✓	✓	✓	qrcode
kuaishou	✓	✓		✓	qrcode
weibo				✓	cookie
xianyu	✓			✓	qrcode
taobao				✓	cookie
jd	✓	✓		✓	qrcode
x				✓	cookie

表格来自注册表，以 catbus <platform> auth login --help 为准。不支持的方式报 UNSUPPORTED，hint 列出可选的方式。

扫码

catbus bilibili auth login
catbus xhs auth login --method qrcode

• 二维码画在终端（stderr）上，同时保存成 PNG：~/.catbus/cache/<platform>/qrcode.png（权限 0600），终端显示不全时打开这张图扫。
• 用对应的 App 扫码，并在手机上确认。扫码后终端会提示「已扫码，请在手机上确认」。
• 要在几分钟内完成（各平台 2～5 分钟不等），超时或二维码失效时报 AUTH_REQUIRED，重新执行即可。
• 小红书：扫码确认后，服务端可能要求做一次人机验证（HTTP 471），catbus 和上游都还不能自动通过，会报 RISK_CONTROL，hint 建议改用 cookie 导入。见 小红书的已知限制。

短信

在终端里（stdin 和 stderr 都是 TTY）一步完成：先发验证码，再提示输入。

catbus kuaishou auth login --method sms --phone 13800000000

在脚本或 Agent 里（非 TTY）分两步，中间态保存在 ~/.catbus/cache/<platform>/，10 分钟内有效：

catbus kuaishou auth login --method sms --phone 13800000000   # 发验证码，data 为 {"sent": true, "phone": "..."}
catbus kuaishou auth login --method sms --code 123456         # 用验证码完成登录

两步要用同一个 -a（不给时都是默认账号）。

平台差异：

• bilibili：发验证码前要过极验。catbus 先自动识别；识别不过时，在终端里会在本机起一个验证页面（127.0.0.1），在浏览器里手动完成后自动继续；非 TTY 下报 RISK_CONTROL，建议改用扫码。
• jd：部分账号在验证码之后还要求「额外安全验证」，会再发一条短信。TTY 下直接提示输入；非 TTY 下报 AUTH_REQUIRED，hint 是用新验证码继续的命令（--code <验证码>）。
• douyin：--sso 改走 login.douyin.com 页的 SSO 链（与上游的 DY_PHONE_LOGIN_PROFILE=sso 相同），只用于 --method sms。
• xhs：短信登录可能同样遇到 471 人机验证。

账密（仅 bilibili）

密码只从 stdin 读取，不接受命令行参数，避免留在 shell 历史里。TTY 下隐藏输入：

catbus bilibili auth login --method password --username <手机号或邮箱> --password-stdin

脚本里从管道传入：

printf '%s' "$BILI_PASSWORD" | catbus bilibili auth login --method password --username <手机号或邮箱> --password-stdin

登录前同样要过极验，处理方式同短信。

导入浏览器 cookie

tiktok、weibo、taobao、x 只能用这种方式；其他平台在扫码被风控时也可以用它。

怎么复制

document.cookie 拿不到 HttpOnly 的 cookie（例如小红书的 web_session、B 站的 SESSDATA、抖音的 sessionid），而它们恰恰是登录态本身，所以一定要从请求头里复制：

1. 用浏览器打开平台网站并登录（见下表的网址）。
2. 打开 DevTools（F12 或 ⌥⌘I），切到 Network（网络） 面板，刷新页面。
3. 点开任意一个发往该网站域名的请求（文档请求或接口请求都行），在 Request Headers（请求标头） 里找到 Cookie，复制它的完整值。
4. 导入：

catbus weibo auth login --cookie "SUB=...; SUBP=...; ..."

默认方式不是 cookie 的平台（扫码为默认）要加 --method cookie：

catbus xhs auth login --method cookie --cookie "a1=...; web_session=...; ..."

cookie 写在命令行里会留在 shell 历史中，更推荐从文件或 stdin 读：

catbus x auth login --cookie @x-cookie.txt     # 从文件读，读完可以删掉这个文件
pbpaste | catbus x auth login --cookie -       # 从 stdin 读（macOS 剪贴板）

--cookie 接受：

• a=1; b=2 形式的 Cookie 请求头（开头带 Cookie: 也可以）；
• 浏览器扩展导出的 cookie JSON 数组（[{"name": ..., "value": ..., "domain": ...}]），会保留各自的 domain 和过期时间；
• douyin、tiktok 另外接受一个 JSON 对象，一并导入写操作需要的设备数据，见下文。

导入后 catbus 会在线校验一次（取当前用户），cookie 无效或过期时报 AUTH_REQUIRED，不保存。

各平台要从哪里复制、至少要有哪些 cookie

平台	网址	catbus 会检查的 cookie
xhs	https://www.xiaohongshu.com	a1（52 位）、web_session
douyin	https://www.douyin.com	sessionid
tiktok	https://www.tiktok.com	sessionid / sid_tt / multi_sids 之一
bilibili	https://www.bilibili.com	SESSDATA；写操作还要 bili_jct
kuaishou	https://www.kuaishou.com	在线校验
weibo	https://weibo.com	SUB
xianyu	https://www.goofish.com	unb，以及 _m_h5_tk、cookie2
taobao	https://www.taobao.com	unb，以及 _m_h5_tk、cookie2
jd	https://www.jd.com	thor（或 pt_key）与 pin
x	https://x.com	auth_token、ct0

缺少时报 USAGE 并说明缺了哪个。复制整条 Cookie 请求头最省事，不要自己挑。

抖音：连同 ticket 与设备素材一起导入

抖音的写操作（发布、评论、点赞、私信等）除了 cookie，还要 bd-ticket-guard 凭证，而且要和 cookie 属于同一次登录。扫码或短信登录时 catbus 会自动拿到这些，所以写操作优先用扫码登录。

只有 cookie 时只读命令正常，写操作会在本地被拦下并报 AUTH_REQUIRED。已经有配套凭证时，可以用一个 JSON 对象导入（格式对应上游 DouyinAuth.from_cookie 的参数）：

{
  "cookie": "<浏览器的完整 Cookie，或 cookie JSON 数组>",
  "ticket": "...",
  "ts_sign": "...",
  "client_cert": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "dtrait_blob": "..."
}

catbus douyin auth login --method cookie --cookie @dy.json

• cookie（也可以写成 cookies）必填，其余可选。
• dtrait 设备素材（dtrait_blob、dtrait_profile、session_dtrait）：不给时按随包的设备档案现算。想用自己浏览器的设备指纹时再导入：dtrait_blob 是抓到的内层 blob，dtrait_profile 是设备档案对象（结构同 static/douyin/dtrait_profile.json），两者都给时 dtrait_blob 优先。
• JSON 里出现任何一个 dtrait 键时，这一组整体替换，值为 null 表示清掉；一个都没有时沿用同名账号已有的。之后再扫码登录同名账号，也会继承已有的 dtrait 素材。

已知问题：目前即使凭证齐全，抖音的发布仍返回空响应（上游同样失败），点赞在缺设备素材时还会导致登录态被踢。详见 抖音的已知限制。

TikTok：导入浏览器会话 JSON

TikTok 只能导入 cookie。只导入 Cookie 字符串时，缺的设备数据会在本地补齐，只读命令可以正常使用；但点赞、收藏、评论、发布、私信、直播发言等写操作需要浏览器 security-sdk 的 ticket-guard 数据，catbus 在本地拦下并报 AUTH_REQUIRED，提示用会话 JSON 重新登录。

会话 JSON 是一个扁平对象，字段名与上游 TiktokApis 的 .tiktok-runtime.json 相同（见上游 README 的「发布 Demo」一节），必须来自同一次已登录的浏览器会话：

{
  "cookie": "<完整的 Cookie 请求头>",
  "document_cookie": "...",
  "device_id": "...",
  "odin_id": "...",
  "user_agent": "...",
  "local_storage": { "...": "..." },
  "session_storage": { "...": "..." },
  "browser_metrics": { "...": "..." },
  "ticket_guard_private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "ticket_guard_encrypt_ticket": "...",
  "ticket_guard_ts_sign": "...",
  "ticket_guard_version": "...",
  "ticket_guard_iteration_version": "..."
}

catbus tiktok auth login --cookie @tiktok-session.json

• cookie 必须是 Cookie 字符串，其余字段原样存进凭证文件的 device。
• 写操作至少要有 ticket_guard_private_key、ticket_guard_encrypt_ticket、ticket_guard_ts_sign；缺哪个，报错里会列出来。
• device_id 不给时，catbus 依次从 localStorage 的 Tea 缓存、multi_sids 里找，再没有就请求一次首页取服务端分配的值。

多账号

每个平台、每个端可以存多个账号，用 -a <账号名> 区分：

catbus xhs auth login -a work             # 登录到账号 work
catbus xhs item search 咖啡 -a work       # 用 work 执行
catbus xhs auth use work                  # 设为当前账号
catbus xhs auth list                      # 本平台的账号
catbus auth list                          # 所有平台、所有端的账号

• 身份的选择顺序：-a <name> > 当前账号 > 未登录。-a 指定的账号不存在时报 AUTH_REQUIRED，hint 为 catbus <p> auth login -a <name>。
• 不带 -a 登录时：有当前账号就登录到当前账号，否则登录到 default。第一次登录的账号自动成为当前账号。
• 账号名只能用小写字母、数字、_ 和 -，以字母或数字开头，最长 32 位。guest 是保留名。
• 如果这个名字下已经存了另一个用户，登录报 USAGE，新凭证不保存：换一个 -a，或者先 auth logout。

子站点（--scope）

有的平台的创作者中心、直播等子站点有单独的登录态：

• 能自动换取的，不需要再登录：例如小红书的创作者中心，第一次用到（item list、item publish 等）时用主站的登录态自动换取；失效后也会自动重新换取。
• 需要单独登录的，用 --scope 登录到同一个账号的对应分区。目前只有小红书声明了 creator：

catbus xhs auth login --scope creator                  # 扫码登录创作者中心
catbus xhs auth login --scope creator --method sms --phone 13800000000
catbus xhs auth login --scope creator --method cookie --cookie @creator-cookie.txt

命令缺少需要的 scope 时报 AUTH_REQUIRED，hint 里带上 --scope。

查看、刷新与登出

catbus xhs auth status      # 在线校验，返回 {logged_in, user, method, expires_at}
catbus xhs auth logout      # 登出当前账号
catbus xhs auth logout -a work

• auth status 未登录或已失效时返回 logged_in: false，不报错；expires_at 取自登录 cookie 的过期时间，取不到时为 null。
• 平台返回登录失效时，命令报 AUTH_EXPIRED（退出码 3），hint 是重新登录的命令。
• 会自动刷新的 token（例如 B 站的 refresh_token）和响应里的 Set-Cookie，会自动合并回凭证文件。
• auth logout 删除本地凭证文件，并清除指向它的当前账号。bilibili 和 kuaishou 会同时调用服务端登出；服务端登出失败时只删本地凭证。

凭证保存在哪里

~/.catbus/auth/<platform>/<endpoint>/<account>.json

• 目录权限 0700、文件 0600（Windows 依赖用户目录本身的 ACL），写入都是原子的。
• 凭证只保存在本机，catbus 不会上传到任何地方。不要把这个目录提交到 git、打包分享，或贴到 issue 里。
• 可以用 CATBUS_HOME 换一个数据目录，见 configuration.md。