{"id":49182537,"url":"https://github.com/983033995/qq-codex-bridge","last_synced_at":"2026-04-23T02:03:46.321Z","repository":{"id":350620527,"uuid":"1207620619","full_name":"983033995/qq-codex-bridge","owner":"983033995","description":"A bridge between QQ Official Bot and Codex Desktop, with media relay, STT, thread management, and incremental reply delivery.","archived":false,"fork":false,"pushed_at":"2026-04-11T07:24:23.000Z","size":3052,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T09:16:36.074Z","etag":null,"topics":["bridge","cdp","codex","electron","qq","qq-bot","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/983033995/qq-codex-bridge","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/983033995.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T07:02:11.000Z","updated_at":"2026-04-11T07:24:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/983033995/qq-codex-bridge","commit_stats":null,"previous_names":["983033995/qq-codex-bridge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/983033995/qq-codex-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/983033995%2Fqq-codex-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/983033995%2Fqq-codex-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/983033995%2Fqq-codex-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/983033995%2Fqq-codex-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/983033995","download_url":"https://codeload.github.com/983033995/qq-codex-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/983033995%2Fqq-codex-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32162614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"online","status_checked_at":"2026-04-23T02:00:06.710Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bridge","cdp","codex","electron","qq","qq-bot","typescript"],"created_at":"2026-04-23T02:03:35.765Z","updated_at":"2026-04-23T02:03:46.304Z","avatar_url":"https://github.com/983033995.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qq-codex-bridge\n\n![CI](https://github.com/983033995/qq-codex-bridge/actions/workflows/ci.yml/badge.svg)\n[![License](https://img.shields.io/github/license/983033995/qq-codex-bridge)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![pnpm](https://img.shields.io/badge/pnpm-10-F69220?logo=pnpm\u0026logoColor=white)](https://pnpm.io/)\n\n![qq-codex-bridge README Hero](./output/readme-hero-nanobanana-productized-v1.png)\n\n## 把 Codex Desktop 变成你的 QQ 私人 AI 助理\n\n不想在浏览器和 QQ 之间来回切换？想把 Codex 的强大能力直接搬到你的 QQ 好友列表和群聊里？\n\n**qq-codex-bridge** 是一个开源桥接工具，它让 Codex Desktop 成为你 QQ 上的实时 AI 对话伙伴——支持图片理解、语音提问、文件分析和 AI 生图回传，私聊群聊都能用。\n\n---\n\n## 你可以这样用\n\n### 发张图片，让 Codex 帮你看\n\n遇到截图、照片、产品图？直接发给机器人，Codex 会结合图片内容给出分析。手机端 QQ、桌面端 QQ 均可使用。\n\n![图片理解](./output/截屏%202026-04-10%2021.33.09.png)\n\n### 语音提问，张口就来\n\n发一条语音，桥接会自动转写后发给 Codex。双手不便打字时，直接说话就能问 AI。\n\n### Markdown 和代码，结构完整回传\n\nCodex 输出的列表、代码块、表格会尽量保留格式后再发到 QQ。写代码、看文档都清晰。\n\n![Markdown 渲染效果](./output/截屏%202026-04-10%2021.31.46.png)\n\n### AI 生成了图片？直接发回 QQ\n\nCodex 调用图片生成工具后，成品会自动回传到 QQ 对话里。创作结果一目了然。\n\n![AI 生图回传](./output/截屏%202026-04-10%2022.00.25.png)\n\n### 私聊线程管理，复杂任务不丢上下文\n\n在 QQ 私聊中直接查看、切换、新建 Codex 线程。大型项目可以分线程讨论，每个线程独立记忆，互不干扰。\n\n![线程管理](./output/截屏%202026-04-10%2021.47.08.png)\n\n---\n\n## 工作原理\n\n```\nQQ 私聊/群聊 ──► 桥接服务 ──► Codex Desktop（CDP 驱动）\n                    ▲                      │\n                    └────── 回复回传 ───────┘\n```\n\n桥接运行在本地 Node.js 进程中，通过 Chrome DevTools Protocol 驱动已运行的 Codex Desktop，完成消息收发和上下文注入。\n\n---\n\n## 快速开始\n\n### 第 0 步：创建 QQ 机器人，获取 AppID 和 AppSecret\n\n1. 打开 [QQ 开放平台](https://q.qq.com/qqbot/openclaw/index.html)，登录后点击「**创建机器人**」\n2. 填写机器人名称和简介，完成创建\n3. 进入机器人详情页，复制 **AppID** 和 **AppSecret**（点击\"查看\"可显示 AppSecret）\n\n![QQ 开放平台机器人创建页面](https://minimax-algeng-chat-tts.oss-cn-wulanchabu.aliyuncs.com/ccv2%2F2026-04-13%2FMiniMax-M2.7%2F2022349168671990452%2F7e608ce17a900fa601a014dc957ef1314be87cff5a110e27615a5393bf2912d6..png?Expires=1776145198\u0026OSSAccessKeyId=LTAI5tGLnRTkBjLuYPjNcKQ8\u0026Signature=eM71QgFWMmELUyeGG2fLn3Onugk%3D)\n\n\u003e 同一 AppID + AppSecret 可以同时在多个群聊和私聊中使用，无需重复创建。\n\n### 第 1 步：生成配置文件\n\n推荐直接用 `npx`：\n\n```bash\nnpx qq-codex-bridge init\n```\n\n或全局安装后使用：\n\n```bash\nnpm i -g qq-codex-bridge\nqq-codex-bridge init\n```\n\n这会将内置配置模板写入当前目录的 `.env`。\n\n### 第 2 步：填写 `.env`\n\n将上一步复制的 **AppID** 和 **AppSecret** 填入 `.env`：\n\n```env\nQQBOT_APP_ID=你的AppID\nQQBOT_CLIENT_SECRET=你的ClientSecret\n```\n\n`.env` 中其他变量说明：\n\n| 变量 | 说明 | 默认值 |\n|---|---|---|\n| `CODEX_REMOTE_DEBUGGING_PORT` | Codex Desktop 远程调试端口 | `9229` |\n| `QQBOT_STT_*` | 语音转文字配置（可选，不填则用 QQ 内置 ASR） | — |\n| `QQBOT_MARKDOWN_SUPPORT` | 是否启用 QQ markdown 文本发送 | `false` |\n\n### 第 3 步：启动桥接\n\n```bash\nnpx qq-codex-bridge\n```\n\n正常启动后会看到类似日志：\n\n```text\n[qq-codex-bridge] codex desktop ready { launched: true|false, remoteDebuggingPort: 9229 }\n[qq-codex-bridge] ready { transport: 'qq-gateway-websocket', accountKey: 'qqbot:default' }\n```\n\n\u003e 桥接会先检查 Codex Desktop 是否已运行；若未运行，会尽量自动拉起后再继续。\n\n### 第 4 步：在 QQ 中联调\n\n建议按这个顺序测试：\n\n1. **普通文本** — 先确认消息收发正常\n2. **一条会让 Codex 分阶段回答的问题** — 验证增量回复采集\n3. **一条语音** — 验证 STT 转写链路\n4. **一张图片** — 验证图片上下文注入\n5. **`/t` 与 `/tu 2`** — 验证线程管理命令\n\n---\n\n## 开发者源码启动\n\n如果你要参与开发、调试源码或运行测试：\n\n```bash\ngit clone https://github.com/983033995/qq-codex-bridge.git\ncd qq-codex-bridge\npnpm install\ncp .env.example .env\n# 填写 .env 中的 QQBOT_APP_ID 和 QQBOT_CLIENT_SECRET\npnpm dev\n```\n\n---\n\n## 技术架构\n\n```text\nQQ Official Bot Gateway\n        │\n        ▼\nQqGatewayClient / QqGateway\n        │\n        ▼\nBridgeOrchestrator\n        │\n        ├── SessionStore / TranscriptStore (SQLite)\n        ├── QqSender / QqApiClient\n        └── CodexDesktopDriver\n                │\n                └── Chrome DevTools Protocol\n                        │\n                        └── Codex Desktop\n```\n\n---\n\n## 项目特性\n\n### 核心能力\n\n- QQ 官方 Bot WebSocket gateway 入站\n- QQ 私聊 / 群聊会话隔离\n- Codex Desktop 启动检查与 CDP 连接\n- QQ 消息映射到 Codex 线程\n- Codex 回复增量采集并多次回传到 QQ\n- SQLite 持久化会话、入站记录、出站任务\n\n### 媒体与语音\n\n- QQ 附件下载与上下文注入（图片、语音、视频、文件）\n- 语音转文字：支持 QQ 内置 ASR / OpenAI 兼容 / 火山引擎 / 本地 whisper.cpp\n- QQ 媒体回传：图片、音频、视频、文件\n\n### Codex 回复处理\n\n- 富文本链接提取、有序列表编号保留\n- 代码块序列化为 fenced markdown、表格结构保留\n- 长耗时任务回复采集窗口延长\n- 同一轮回复中的媒体结果持续跟进，不再只截前几段文本\n\n### 线程管理命令\n\n仅私聊可用：\n\n| 用途 | 完整命令 | 简写 |\n| --- | --- | --- |\n| 查看最近活跃线程 | `/threads` | `/t` |\n| 查看当前绑定线程 | `/thread current` | `/tc` |\n| 切换到指定线程 | `/thread use \u003c序号\u003e` | `/tu \u003c序号\u003e` |\n| 新建线程 | `/thread new \u003c标题\u003e` | `/tn \u003c标题\u003e` |\n| 基于最近对话 fork 线程 | `/thread fork \u003c标题\u003e` | `/tf \u003c标题\u003e` |\n| 查看当前模型 | `/model` | `/m` |\n| 切换模型 | `/model use \u003c名称\u003e` | `/mu \u003c名称\u003e` |\n| 查看额度信息 | `/quota` | `/q` |\n| 查看当前运行状态 | `/status` | `/st` |\n| 查看帮助 | `/help` | `/h` |\n\n---\n\n## 当前实现上的保护逻辑\n\n这几个是和\"最小 demo\"相比的重要工程细节：\n\n- **重复 QQ 入站抑制** — 短时间内同一会话、同一正文、同一媒体指纹的重复消息会被拦下\n- **长耗时任务回复采集窗口延长** — 图片生成、长搜索、长工具执行不再因默认 30 秒窗口被提前截断\n- **单条 draft 发送失败不再截断整轮回复** — 某一条 QQ 发送失败时，后续 draft 仍会继续尝试\n- **可恢复错误不会把整个桥接打成不可用** — 例如 `reply_timeout` 被当成可恢复错误，不再直接把会话打成 `needs_rebind`\n\n---\n\n## 已知限制\n\n- 核心能力依赖 Codex Desktop 当前版本的 DOM 结构和 CDP 可见性，桌面端改版后可能需要跟着适配\n- 对 Codex 回复的增量采集是**基于页面快照的伪流式**，不是官方内部事件流\n- QQ 客户端的消息样式、Markdown 支持、媒体卡片展示不完全可控\n- 线程管理命令目前只在 **QQ 私聊** 中开放\n- 某些极端场景下，如果 Codex Desktop 页面结构变化很大，线程定位与回复提取可能失效\n\n---\n\n## 环境要求\n\n- macOS\n- Node.js 20+\n- 已安装 Codex Desktop\n- Codex Desktop 可通过远程调试端口暴露 page target\n- QQ 官方机器人 `AppID` 和 `ClientSecret`\n\n---\n\n## 安全提醒\n\n- `.env` 里会包含 QQ Bot、STT 等敏感密钥，**不要提交到仓库**\n- 如果你把项目分享给别人，请务必轮换已经暴露过的密钥\n- 本项目会处理用户消息、附件、语音与本地文件路径，联调时请注意隐私边界\n\n---\n\n## 调试建议\n\n```bash\n# 类型检查\npnpm run check\n\n# 运行测试\npnpm test\n\n# 调试 Codex page / worker\npnpm run debug:codex-workers -- --duration-ms 12000\n```\n\n---\n\n## 文档导航\n\n- [FAQ 与故障排查](./docs/faq.md)\n- [架构说明](./docs/architecture.md)\n- [测试说明](./docs/testing.md)\n- [变更记录](./CHANGELOG.md)\n- [贡献指南](./CONTRIBUTING.md)\n- [安全策略](./SECURITY.md)\n- [在线 Wiki（GitNexus 自动生成）](https://gistcdn.githack.com/983033995/e5715ad0d61605f039ca4e6055094083/raw/index.html#overview)\n\n---\n\n## 贡献\n\n欢迎 issue、讨论和 PR。在提交改动前，建议至少执行：\n\n```bash\npnpm run check\npnpm test\n```\n\n更多约定请看 [CONTRIBUTING.md](./CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)。\n\n---\n\n## License\n\n本仓库使用 [MIT License](./LICENSE)。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F983033995%2Fqq-codex-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F983033995%2Fqq-codex-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F983033995%2Fqq-codex-bridge/lists"}