Onyx Auto Register Local Bridge

本项目用于配合 Tampermonkey 脚本 register.js 完成以下流程：

• 自动注册 Onyx 账号
• 通过 DuckDuckGo Email Protection 申请私有别名
• 通过 IMAP 轮询真实邮箱，抓取 Onyx 验证邮件中的验证链接
• 注册成功后把账号、Cookie 上报到本地后端保存
• 验证完成后继续创建 Agent、配置聊天偏好

当前仓库的本地后端由 app.py 提供入口，并挂载 duckduckgo_email.py 中的 DuckDuckGo/IMAP 路由。

文件说明

• register.js：Tampermonkey 用户脚本，负责浏览器端自动化注册流程
• duckduckgo_email.py：FastAPI 路由，负责 DuckDuckGo 私有别名申请与 IMAP 邮件轮询
• app.py：FastAPI 应用入口，提供：
  • /api/duckduckgo-email/*
  • /api/onyx-cookies/append
  • /api/onyx-accounts/append
  • /api/healthz
• requirements.txt：Python 依赖清单
• .env.example：环境变量模板，列出 DuckDuckGo Mail / IMAP / 本地接口所需配置

环境要求

• Python 3.10+
• 一个可用的 DuckDuckGo Email Protection Token
• 一个支持 IMAP 的真实邮箱
• 已安装 Tampermonkey 或同类用户脚本扩展

安装依赖

pip install -r requirements.txt

DuckDuckGo Mail 需要配置哪些项

要让 register.js + duckduckgo_email.py 正常工作，至少要准备以下配置。

1. DuckDuckGo 私有别名配置

必填项：

• DUCK_TOKEN：DuckDuckGo Email Protection 的访问令牌
• DUCK_API_BASE：通常为 https://quack.duckduckgo.com
• DUCK_ALIAS_CREATE_PATH：通常为 /api/email/addresses

一般保持默认即可：

• DUCK_TOKEN_HEADER_NAME：默认 Authorization
• DUCK_TOKEN_PREFIX：默认 Bearer
• DUCK_EXTRA_HEADERS：额外请求头，没有特殊需求可保留 {}

2. IMAP 邮箱配置

DuckDuckGo 私有别名收到的邮件会转发到你的真实邮箱，所以必须配置 IMAP 读取真实邮箱。

必填项：

• IMAP_HOST
• IMAP_PORT
• IMAP_USERNAME
• IMAP_PASSWORD

常用可选项：

• IMAP_FOLDERS：默认 INBOX，如果邮件会进入其它文件夹，可写多个，逗号分隔

3. 本地桥接/落盘接口配置

必填项：

• DUCK_BRIDGE_BASE_URL
• APPEND_COOKIE_URL
• APPEND_ACCOUNT_URL

环境变量文件

仓库中已新增 .env.example。可以复制为本地私有文件后再填写：

Windows CMD

copy .env.example .env

Linux / macOS

cp .env.example .env

需要重点填写的字段如下：

DUCK_TOKEN=
IMAP_HOST=
IMAP_PORT=993
IMAP_USERNAME=
IMAP_PASSWORD=
IMAP_FOLDERS=INBOX
DUCK_BRIDGE_BASE_URL=http://127.0.0.1:9898/api/duckduckgo-email
APPEND_COOKIE_URL=http://127.0.0.1:9898/api/onyx-cookies/append
APPEND_ACCOUNT_URL=http://127.0.0.1:9898/api/onyx-accounts/append

启动后端

Windows CMD

直接启动服务：

python app.py

默认监听：

• http://127.0.0.1:9898：账号/Cookie 落盘接口
• DuckDuckGo 桥接接口同样由当前服务提供：/api/duckduckgo-email/*

例如：

• POST /api/duckduckgo-email/session/start
• GET /api/duckduckgo-email/session/poll
• POST /api/onyx-cookies/append
• POST /api/onyx-accounts/append

接口文档地址：

• http://127.0.0.1:9898/docs

register.js 配置说明

请编辑 register.js 顶部的 CONFIG，至少填写以下字段。

DuckDuckGo 相关

• DUCK_BRIDGE_BASE_URL
• DUCK_API_BASE
• DUCK_ALIAS_CREATE_PATH
• DUCK_TOKEN
• DUCK_TOKEN_HEADER_NAME
• DUCK_TOKEN_PREFIX
• DUCK_EXTRA_HEADERS

默认情况下，本地桥接地址建议改成当前后端端口：

DUCK_BRIDGE_BASE_URL: 'http://127.0.0.1:9898/api/duckduckgo-email'

IMAP 相关

• IMAP_HOST
• IMAP_PORT
• IMAP_USERNAME
• IMAP_PASSWORD
• IMAP_FOLDERS

本地落盘接口相关

• APPEND_COOKIE_URL
• APPEND_ACCOUNT_URL

推荐配置为：

APPEND_COOKIE_URL: 'http://127.0.0.1:9898/api/onyx-cookies/append',
APPEND_ACCOUNT_URL: 'http://127.0.0.1:9898/api/onyx-accounts/append',

数据存储

运行后会自动创建 data/ 目录，并生成：

• data/onyx_cookies.json
• data/onyx_accounts.json

去重规则

• Cookie：按完整 cookie 字符串去重
• 账号：按 email 去重；若重复会执行覆盖更新，并刷新 updated_at

安全说明

• 不要把真实的 DUCK_TOKEN、IMAP 密码提交到公共仓库
• 推荐使用邮箱应用专用密码，而不是邮箱主密码
• .env.example 只是模板，不应直接保存真实密钥

常见问题

1. 默认端口是多少？

当前项目默认端口已统一为 9898。

例如：

uvicorn app:app --host 127.0.0.1 --port 9898

如果你改成其它端口，记得同步修改 register.js 与 .env.example 中的本地接口地址。

2. 收不到验证邮件怎么办？

排查以下内容：

• DUCK_TOKEN 是否有效
• 真实邮箱是否已开启 IMAP
• IMAP_HOST / IMAP_PORT / IMAP_USERNAME / IMAP_PASSWORD 是否正确
• IMAP_FOLDERS 是否对应邮件实际落入的文件夹
• 邮件是否被归档、进入垃圾箱或其它分类目录

3. 写入账号/Cookie 失败怎么办？

优先检查以下内容：

• 本地服务 app.py 是否已经启动
• APPEND_COOKIE_URL / APPEND_ACCOUNT_URL 是否填写正确
• 浏览器是否能访问本地接口地址

推荐启动方式

如果希望所有接口统一走一个端口，建议直接把 register.js 中以下配置全部保持为 9898：

DUCK_BRIDGE_BASE_URL: 'http://127.0.0.1:9898/api/duckduckgo-email',
APPEND_COOKIE_URL: 'http://127.0.0.1:9898/api/onyx-cookies/append',
APPEND_ACCOUNT_URL: 'http://127.0.0.1:9898/api/onyx-accounts/append',

这样 app.py 可作为单一入口直接运行。