QBot

将 QQ Bot v2 接入本机 Codex CLI 的 macOS 网关，不安装也不依赖 OpenClaw。安装后可直接在 QQ 中让 Codex 编写代码、处理附件、回传文件、管理待办，或托管局域网网页服务；不依赖 OpenClaw。

你可以做什么

• 在私聊、群聊或频道中持续与 Codex 协作；每个对话保留独立上下文
• 发送图片、文本、代码、JSON、CSV、PDF 等附件，并要求机器人回传工作区中的产物
• 用自然语言创建一次性或周期性提醒；网关重启后会补推历史逾期待办
• 让 Agent 启动局域网网页服务，并在 QQ 中查询或停止服务
• 通过本地 QBot Console 配置机器人、查看体检、待办和运行状态
• 创建多个彼此隔离的机器人实例

环境要求

| 项目 | 要求 | 检查方式 | | --- | --- | --- | | 操作系统 | macOS | QBot 当前仅支持 macOS | | Node.js | >= 22.5.0 | node --version | | Codex CLI | 已安装且可运行 | codex --version | | Codex 登录 | 已完成登录 | codex login status | | QQ 机器人 | QQ 开放平台 AppID 与 AppSecret | QQ 开放平台 | | 授权用户 | user_openid 或 member_openid | 管理台发现模式或开放平台 |

浏览器采集是可选能力，还需安装 Python Playwright 与 Chromium：

pip install playwright
playwright install chromium

快速开始

1. 安装

npm install -g @eos./qbot

确认命令可用：

qbot --version
qbot --help

2. 打开 QBot Console

qbot dashboard 是首次配置和日常管理的主入口：它会自动创建 ~/.qq-codex-workspaces/，生成私有的 .env 与 soul.md，并打开可视化控制台

qbot dashboard

根据引导完成配置

| 文件 | 用途 | | --- | --- | | ~/.qq-codex-workspaces/.env | 机器人配置与密钥，权限为 0600 | | ~/.qq-codex-workspaces/soul.md | 机器人角色设定 |

若尚未安装或登录 Codex CLI：

npm install -g @openai/codex
codex login

3. 在控制台配置机器人

在 QBot Console 的“配置设置”中填写 AppID、AppSecret 与授权 OpenID；保存后，流式、Markdown 和白名单会自动热加载

| 配置项 | 填写内容 | | --- | --- | | QQ_APP_ID | QQ 开放平台 AppID | | QQ_APP_SECRET | QQ 开放平台 AppSecret | | QQ_ALLOWED_SENDERS | 逗号分隔的授权 OpenID |

私聊使用 user_openid，群聊使用 member_openid，均不是普通 QQ 号。不知道 OpenID 时可先留空；启动网关后，控制台会在“配置设置”中提供私聊发现的 OpenID，采用后重启网关

也可直接编辑 ~/.qq-codex-workspaces/.env，但首次配置优先使用控制台，避免路径、格式和 OpenID 类型错误

4. 启动机器人

保持 QBot Console 运行，并在另一个终端启动 QQ 网关、待办调度器和浏览器采集服务：

qbot start

看到下列日志表示 QQ 网关已就绪：

QQ bot is online (READY)

控制台用于查看状态、配置、待办与角色设定；按 Ctrl+C 停止对应前台进程。命令行体检可随时执行：

qbot doctor

日常使用

在 QQ 中发起任务

直接向已授权的机器人发送消息即可。私聊各自延续上下文；群聊和频道按会话共享上下文；同一会话中的任务会按顺序执行

帮我检查当前项目的测试失败原因
把生成的报告发给我
提醒我 1 小时后喝水
每天 9 点在 Asia/Shanghai 提醒我站会

对话命令

| 命令 | 作用 | | --- | --- | | /reset | 清除当前上下文，下一条消息创建新会话 | | /new <任务> | 清除当前上下文并立即开始新任务 | | /new ter <任务> | 使用 ter 模型开始新上下文 | | /new sol <任务> | 使用 sol 模型开始新上下文 | | /new luna <任务> | 使用 luna 模型开始新上下文 | | /rotate [任务] | 生成当前会话交接摘要并切换到新上下文 | | /stop 或 /cancel | 中断当前任务，并取消同一会话的排队任务 |

附件与文件回传

可发送图片、文本、代码、JSON、CSV、PDF 等文件。压缩包和可执行文件会被拒绝；

让 Agent 回传文件时直接说明需求：

把生成的报告发给我

常驻网页服务

让 Agent 创建网页后，可用自然语言要求它启动服务：

做一个局域网聊天网页，启动后把地址发给我
查看聊天网页服务状态
停止聊天网页服务

QBot 会托管服务、检查健康状态并回传实际局域网地址。服务能跨 QQ 对话存活，但网关重启后需要重新启动

项目目录切换

设置 QQ_PROJECT_ROOT 后，可在其一层子目录间切换项目：

/dir
/dir 2
/dir new 新项目名称

切换后，每个项目都有独立上下文，切回时会恢复原对话。QQ_PROJECT_ROOT 不是安全沙箱：所有白名单用户都能让 Codex 读写所选项目；只配置可信用户和专用项目目录

配置参考

完整注释见 ~/.qq-codex-workspaces/.env。常用配置如下：

| 配置 | 默认值 | 用途 | 修改后 | | --- | --- | --- | --- | | QQ_ALLOWED_SENDERS | 空 | 授权 OpenID 白名单 | 管理台采用时热加载；手改后重启网关 | | QQ_MARKDOWN_ENABLED | true | QQ 客户端 Markdown 渲染 | 管理台保存后下一条消息生效 | | QQ_STREAM_ENABLED | true | 私聊实时更新回复 | 管理台保存后下一条消息生效 | | QQ_STREAM_MODE | reply | reply 仅流式回复；exec 额外显示执行进度 | 管理台保存后下一条消息生效 | | QQ_CONTEXT_ROTATE_AT | 70 | 自动轮换上下文的百分比阈值 | 重启网关 | | QQ_SERVICES | true | 是否允许 Agent 托管常驻服务 | 重启网关 | | QQ_TODO_SCRIPT_TIMEOUT_MS | 300000 | 定时脚本最长运行时间（毫秒） | 重启网关 | | QQ_GIT_WRITE_ENABLED | false | 是否允许 Agent 写 Git 元数据（暂存、提交） | 管理台保存后下一条消息生效 | | 软件更新检查 | 默认机器人启动后每 5 天 | 检查 npm；有新版本时私聊推送升级命令 | 不自动下载或安装 | | QQ_WORKSPACE_ROOT | ~/.qq-codex-workspaces/ | 会话工作区根目录 | 重启网关 | | QQ_PROJECT_ROOT | 未设置 | 启用 /dir 项目选择 | 重启网关 | | QQ_BROWSER_CAPTURE_PORT | 19200 | 浏览器采集服务端口；设 0 禁用 | 重启网关 | | DASHBOARD_PORT | 19201 | 本地管理台端口 | 重启管理台 | | QQ_SERVICE_PORT_RANGE | 19202-19209 | Agent 可使用的常驻网页服务端口 | 重启网关 |

修改密钥或大多数环境变量后，停止并重新执行 qbot start。从管理台修改流式、Markdown 和白名单配置时，会自动向运行中的网关发送热加载信号

管理多个机器人

创建命名实例：

qbot new wife

命令会创建 ~/.qq-codex-workspaces/multi_bots/wife/，复制独立的 .env 与 soul.md，并自动登记可用端口组。填写该实例的 .env 后分别运行：

qbot start wife
qbot dashboard wife
qbot doctor wife

| 资源 | 是否实例隔离 | | --- | --- | | QQ 凭据、会话、附件、待办、角色设定、工作区、管理台端口 | 是 | | 浏览器采集与常驻网页服务端口 | 是，按十个连续端口自动分组 | | Codex 登录态与 $CODEX_HOME | 否，机器级共享 |

每个实例从 19200 起占用一组连续十个端口：浏览器采集为组起点，管理台为起点加 1，网页服务使用起点加 2 至加 9。实际分配以 ~/.qq-codex-workspaces/app_config.json 为准

不要让两个机器人共用同一个 QQ_PROJECT_ROOT。若需并行操作同一代码库，请为它们分配不同 Git worktree

常见问题

| 现象 | 排查与处理 | | --- | --- | | qbot: command not found | 重新打开终端，或将 $(npm config get prefix)/bin 加入 PATH | | qbot doctor 显示 Node 或 Codex 不通过 | 按 JSON 输出的 fix 操作，确认 Node.js ≥ 22.5 与 codex login 已完成 | | 没有 READY 日志 | 检查 ~/.qq-codex-workspaces/.env 中的 AppID、AppSecret、网络与终端错误日志 | | QQ 消息无回复 | 确认网关仍在运行、发送者的 OpenID 已在 QQ_ALLOWED_SENDERS 内，并查看 received ... 日志 | | 不知道 OpenID | 清空白名单后启动，在管理台拉取私聊发现的 OpenID；采用后重启网关 | | Markdown 显示异常 | 将 QQ_MARKDOWN_ENABLED=false，在管理台保存或重启网关 | | 手机打不开网页服务 | 确认手机和 Mac 在同一子网，并检查 macOS 防火墙、路由器客户端隔离与 Agent 返回的地址 | | 浏览器采集不可用 | 安装 pip install playwright 与 playwright install chromium，或将 QQ_BROWSER_CAPTURE_PORT=0 禁用该可选功能 | | 修改 .env 后未生效 | 绝大多数配置需停止并重新执行 qbot start；仅管理台保存的白名单、流式和 Markdown 支持热加载 |

命令速查

qbot --help             查看帮助
qbot --version          查看版本
qbot doctor [name]      检查默认或命名实例的运行条件
qbot start [name]       启动 QQ 网关、待办与可选浏览器采集
qbot dashboard [name]   启动本地管理台
qbot new <name>         创建隔离的命名机器人实例