独立 API 登录

使用 ~/.openclaw/douyin-api/session.json，权限 0600；设置 DOUYIN_API_SESSION 时使用指定入口。重新登录后该入口保存新会话文件的位置，全部抖音工具自动读取同一新会话，实际路径由 status.session_file 返回。采集、发布、私信、互动和直播共用此会话。Relay 提供设备配置、协议配置与加密运行句柄；客户端直接请求平台并保存 Cookie，不启动浏览器。

首次扫码登录

先运行 douyin-login relay-check 和 douyin-login status。Relay 检查应返回 automatic_login: true。会话不存在时直接初始化；无需准备 config.json、私钥或一次性挑战文件，也不要安排其他智能体生成这些材料。

douyin-login init
douyin-login qr --output /受控目录/douyin-qr.png

init 自动完成匿名设备注册、设备挑战与响应处理，成功返回 next: qr。把 qr 生成的图片交给用户扫码，然后运行：

douyin-login poll --timeout 120

程序处理登录重定向并查询本人资料；返回 logged_in: true 和已确认 UID 后，才能使用平台业务工具。再执行 douyin-hunter check 和 douyin-engagement check。

status 中的 cookie_present 只表示主站作用域内存在未过期会话 Cookie；identity_verified 表示有效会话已通过本人身份读取并缓存 UID，logged_in 与此一致。只有 Cookie 而没有 UID，且没有未完成验证、runtime 未过期时，执行 douyin-hunter check 验证现有会话；过期二维码不代表账号已登出，不要仅因此重新初始化。

已有账号需要刷新互动安全材料时执行 douyin-login refresh。工具先读取本人身份，再续接当前会话的安全握手；账号、UA 和会话密钥保持绑定，不重新扫码。只保存加密运行句柄、材料名称清单和秒级有效期，不手工补材料值。互动工具提示材料缺少或即将过期时先执行此刷新；账号发生变化或刷新失败时停止写操作。

彻底清空本地账号与换号

用户要求彻底清空本地账号时，先结束抖音业务请求和未完成的登录流程，再删除会话入口、status.session_file 指向的实际文件、同一账号含凭据的备份和登录临时文件；保留业务数据及其他平台会话。默认登录目录内的 sessions/login-*、session.abandoned-* 也可能保存历史会话，清空要求覆盖它们。换号或用户明确要求重新登录时执行 douyin-login restart --confirm，再获取二维码或按用户选择发起短信登录；登录后核对 UID。该命令保留旧诊断为私有备份，在新的仓外文件中调用 passport.initialize，弃用旧 runtime、Cookie、QR、短信与 MFA 状态，所有工具自动切换。它不会发送短信或验证码。直接重复 init 只复用原状态，不会换号；需要保留多个账号时可分别设置仓外 DOUYIN_API_SESSION，各账号工具使用对应入口，旧会话以 0600 权限保存。

登录超时与重新登录

客户端同时保存 Relay 返回的 runtime 和秒级 runtime_expires_at。未完成登录从首次初始化起固定 15 分钟；轮询、新句柄和计算重试均不延期。成功平台登录后 Relay 返回较长有效期，仍须真实 self 确认 UID。MFA 最多 600 秒，以及二维码、验证码、安全材料各自的有效期仍需满足；runtime 有效不代表这些材料有效。

status.runtime_expired: true 或错误 RUNTIME_EXPIRED 时停止原登录与业务请求，向用户提示“本次登录已超时，请重新登录”，保留原响应供私有诊断。普通 init 不会自动重置。用户明确选择重新登录后执行：

douyin-login restart --confirm