快速开始

真正登录并收发消息需要同时具备两样东西：

1. 一个真实 QQ 账号（uin + 密码，或扫码登录）；
2. 一个外部 sign server（qsign / unidbg-fetch-qsign / 兼容 T544），地址填到 account.sign_api_url。

关于 sign server

请自行寻找合适的 sign server（签名服务），本项目不提供、不内置、不推荐任何 sign server。 现代 QQ 协议要求每个请求包都带签名，没有 sign server 无法登录。

步骤

1. 部署 / 获取一个 sign server

记下它的基址（例如 <sign-server-url>），稍后填到配置的 account.sign_api_url。 注意：apk_ver 必须匹配该 sign server 白盒支持的 QQ 版本，否则会被服务端拒绝。

2. 建配置

把示例配置复制为 config.yaml：

cp config.example.yaml config.yaml

然后填好关键字段：

• account.uin —— 你的 QQ 号；
• account.password —— 明文或 32 位小写 MD5（留空则走扫码登录）；
• account.sign_api_url —— 第 1 步记下的 sign server 基址；
• account.platform —— 平台代码（1 = 安卓手机）；
• account.apk_ver —— 与 sign server 白盒一致的 QQ 版本；
• 至少启用一种传输：http / ws / ws_reverse 之一的 enable: true。

各字段含义见配置说明。

敏感值（uin / 密码 / sign server / token 等）也可用 ICQQ_* 环境变量注入（env 优先于 config.yaml），避免明文落盘 —— 见下文「环境变量注入」。

3. 运行

cargo run -p icqq-app -- config.yaml

省略路径参数时，程序默认读取 ./config.yaml。

4. 观察启动

启动后会自动连接 sign server 并登录 QQ。登录成功后，你配置的 HTTP / WebSocket 接口就可以接收请求了。

• 首次新设备需要在手机 QQ 里确认一次设备验证；
• 可能遇到选图验证码；
• 登录细节与诊断见仓库内部文档。

环境变量注入

以下环境变量可覆盖 config.yaml 中的对应值（环境变量优先），方便把密码等敏感信息从配置文件移到环境变量。

环境变量	覆盖的配置字段
ICQQ_UIN	account.uin
ICQQ_PASSWORD	account.password
ICQQ_SIGN_API_URL	account.sign_api_url
ICQQ_PLATFORM	account.platform
ICQQ_APK_VER	account.apk_ver
ICQQ_LOGIN_METHOD	account.login_method
ICQQ_DATA_DIR	data_dir
ICQQ_HTTP_ACCESS_TOKEN	http.access_token

例如（仅用环境变量注入敏感值，配置文件里留占位/空）：

export ICQQ_UIN=<your-uin>
export ICQQ_PASSWORD=<your-password>
export ICQQ_SIGN_API_URL=<sign-server-url>
export ICQQ_PLATFORM=1
export ICQQ_APK_VER=9.2.0
cargo run -p icqq-app -- config.yaml

验证 HTTP 接口

若启用了 HTTP 传输（默认 host: 127.0.0.1、port: 5700），可以发一个 action 试试：

curl -X POST http://127.0.0.1:5700/send_private_msg \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"user_id": <friend_id>, "message": "hello"}'

完整 action 列表见 API 参考。