实例隔离与恢复

无需 YunLeFun 账户或额外控制台。QQ 官方 AppID / AppSecret 用于机器人鉴权，本机 Codex 登录用于模型访问；首次 /pair 将遥控权限限定到自己的 QQ。已有本人绑定会在重启后保留。

创建独立实例

每个机器人或环境使用一个名称，例如 personal、test。名称只允许小写字母、数字、下划线和短横线，最长 64 个字符。

pnpm add -g el-bot@next
el-bot codex --profile personal init --project /absolute/path/to/my-project --name my-project
el-bot codex --profile personal paths

内容	personal 实例的默认路径
配置	~/.el-bot/codex/personal/config.json
QQ 凭据	~/.el-bot/codex/personal/credentials.env
绑定、任务和会话索引	~/.el-bot/codex/personal/state.json
Codex 账户配置与会话	~/.el-bot/codex/personal/codex/

新 profile 使用独立 CODEX_HOME，需要在该目录登录 Codex。请使用 paths 显示的绝对路径；以下是 macOS / Linux 示例：

CODEX_HOME="$HOME/.el-bot/codex/personal/codex" codex login
el-bot codex --profile personal check --all
el-bot codex --profile personal check --all --json
el-bot codex --profile personal start

Windows PowerShell 先设置 $env:CODEX_HOME 为 paths 的 codexHome，再执行 codex login。不要复制或上传另一个实例的登录文件。 初始化、检查、恢复和启动都应传入相同的 --profile。首启后把终端显示的 /pair 绑定码私聊发给机器人，后续启动无需重复绑定。

profile 的配置、凭据和状态目录独立，Codex 子进程也不会默认继承宿主的 OPENAI_API_KEY 等提供方密钥。需要自定义服务环境变量时，在配置中用 codexEnvAllowlist 指定变量名，例如 ["OPENAI_API_KEY"]，由运行服务的环境提供值。平台运行变量、语言和代理设置继续可用；QQ_BOT_* 始终不传给 Codex。 这是账户和文件布局隔离，同一系统用户仍可访问这些目录；它不是容器或操作系统权限边界。

自动校验机器人与环境

首次启动会将状态固定到 AppID、QQ 测试环境 sandbox、profile 名称和 Codex 目录，无需另一次绑定操作。之后误用另一机器人的凭据、测试环境或 Codex 目录会在连接前报错，保留原绑定和历史。

旧版状态没有 AppID 元数据。升级后首次启动使用当次本机凭据接管，先生成 state.json.before-instance.json 私有备份，再保存元数据；它无法推断旧状态原本属于哪个 AppID。升级前请用 paths 核对原文件并确认凭据属于原机器人，不要删除状态来绕过检查。

显式 --credentials 或 --profile 只读取指定实例的凭据文件，不接受环境变量覆盖，也不回退到当前目录 .env。AppID 和 AppSecret 必须来自同一个来源，缺少其中之一就报错。 默认模式继续按「完整进程环境 → 默认凭据文件 → 当前目录 .env」读取，任何来源只有半套凭据时都不会与另一个来源拼接。

未指定 profile 时，旧配置、凭据和状态路径继续有效，Codex 沿用本机目录，已有绑定无需迁移。仅更换 --config 不会自动隔离凭据和状态；建议新实例使用 profile。 如果要保留原 Codex 目录，也可以显式使用三组独立路径：--config、--credentials、--state。不要让多个进程共享状态文件。

归档检测与连接诊断

el-bot codex --profile personal check --all

检查会读取会话并分页查询归档列表，区分可续聊、已归档、丢失和项目路径变化。启动时提示不可续聊的项目，但保留 QQ 查询与恢复入口；每次续聊前再次检查，不会自动取消归档或重放任务。 在 QQ 中发送 /diagnose [项目]，可以只读查询对应项目的会话状态，不调用模型。连接断开时，会提示在本机检查和重启。 check --all 另外验证本机账户、模型预检、QQ 鉴权和网关访问；它不启动模型任务或 QQ 长连接。最终是否接通仍需用户在 QQ 发送测试任务并收到结果。

检查会汇总各项结果：归档会话或本机 Codex 失败不会遮住独立的 QQ 检查；AppID / 环境身份不匹配则阻止连接。 PASS 表示预检通过，FAIL 表示需要处理，SKIP 表示前置条件不满足。任一失败的退出码为 1。 --json 输出 version、ok 和 checks；每项包含 id、status、summary，失败时提供 actions。 修复命令保留本次 profile 和配置 / 凭据 / 状态路径，适合交给 AI 继续排错。报告不包含密钥、主人 ID、会话 ID 或原始服务端错误；本机路径仍应视为私人信息。 只有显式运行 recover 才改变续聊索引；诊断不会重置绑定、自动取消归档或重试任务。

明确恢复，不丢历史

失败卡片按原因提供「连接诊断」「新建会话」按钮。新建按钮绑定失败任务所属的项目，避免切换项目后误改当前项目。

• 服务在线：发送 /new my-project，清除该项目的续聊索引；省略项目时使用当前项目。
• 服务不可用：先停止进程，再在本机运行 el-bot codex --profile personal recover --project my-project。
• 想沿用已有会话：核对原账户、目录和归档状态后，使用 /thread use 会话ID。归档会话须由用户明确取消归档后再绑定。

本机 recover 会先备份原状态并检查实例身份和状态锁，只清除指定项目的续聊绑定。本人绑定、其他项目、任务结果、消息去重记录和原 Codex 会话都保留。 恢复命令不连接 QQ、不启动模型，也不自动重试失败任务；下一条用户任务才创建新会话。备份文件含私人会话信息，勿提交到 Git 或上传。

与 Desktop 连接的区别

codexConnection: "desktop" 使用桌面正在运行的后端，账户和会话目录由桌面决定，因此不支持 profile 的独立 Codex 目录。需要连接该后端时，使用独立 --config、--credentials、--state 隔离机器人数据，并遵循 Desktop 接入。 默认 stdio 的 profile 可以单独配置桌面宿主工具；宿主工具仍操作桌面自己的账户与数据，其权限不受 profile 的 Codex 目录隔离。