openclaw-voc-skill/claude-code/claude-code-qiwe-assistant/skills/qiwei-login/SKILL.md

---

name: qiwei-login

description: 通过 Fmode 网关转发的企业微信接口完成扫码登录和订阅管理。适用于首次使用、设备掉线、qiwei_api_call 返回 needs_login、订阅未开通或席位不足；客户端只使用 Fmode 鉴权 token 和 uid，企业微信接口访问凭据由 Fmode 网关管理。

企业微信扫码登录

严格流程

1. 检查订阅：调用 qiwei_subscription_status。
   • 未订阅或已到期：调用 qiwei_subscribe；
   • 席位已满：用 qiwei_subscribe 传新的总 seats 数增购；
   • 余额不足：引导用户充值飞马余额后重试。
2. 检查设备：调用 qiwei_login_status。
   • online=true：无需重新登录；
   • 未配置或离线：继续下一步。
3. 生成二维码：调用 qiwei_login_start。
   • 工具通过 /api/qiwei/login/start 请求 Fmode 网关；
   • 二维码保存到 outputs/qiwei-login-qrcode.png，默认打开 HTML 预览；
   • 把二维码展示给用户，用手机企业微信扫码并确认。
4. 轮询状态：每 3–5 秒调用 qiwei_login_check。
   • -1 / 1：继续等待；
   • 0：可传 manual: true 尝试免扫码登录；
   • 2：登录成功；
   • 4：用户取消，重新调用 qiwei_login_start；
   • 10：进入验证码流程。
5. 验证码：状态 10 时向用户索要手机端显示的 6 位验证码，调用 qiwei_login_verify，然后再次检查状态。
6. 验证业务链路：登录成功后调用 qiwei_api_call（例如 user.getProfile）。

新账号与多账号切换

• “添加账号”必须为新账号生成新的 uid，启动、轮询和验证码请求始终携带同一个新 uid；新 uid 不复用当前账号的 guid。
• 扫码完成前使用 persistConfig=false，不提前覆盖当前项目配置；状态为 2 后再保存新账号并调用 Dashboard 的账号切换接口。
• 切换成功后同时持久化 QIWEI_UID 与对应 QIWEI_GUID；新账号没有 GUID 时必须清除旧 GUID，不得形成跨账号组合。
• 浏览器账号列表按 workspaceId 隔离。同一浏览器访问多个克隆项目时，不得把其他项目的当前账号自动写入本项目。
• 用户取消扫码或切换接口失败时恢复原当前账号；已经保存的其他账号继续保留，可再次选择。
• 切换账号会切换独立 Workbench 数据库和 Claude 客户 Session；监听重启只恢复连接，不改变原有审核/自动/人工模式。

配置

• QIWEI_API_BASE 默认 https://server.fmode.cn/api/qiwei；
• Fmode token 自动从 Claude Code / Fmode 配置读取，也可显式设置 QIWEI_AUTH_TOKEN；
• QIWEI_UID 未配置时自动生成并持久化；
• 不读取、保存或要求用户提供企业微信接口访问凭据。

安全约定

• 不展示或记录 Authorization 和 Fmode token；
• 不向用户暴露接口服务提供方名称、相关域名或控制台；
• 不绕过 Fmode 网关直连内部服务；
• 不通过 qiwei_api_call 调用 /login/* 或 /client/*。
• 不在对话、日志或测试报告中回显 Token、GUID 或完整账号标识。