@ezerlab/claude-codex

本机 MVP：Claude Code 保留主交互、上下文、权限与原生工具，CLIProxyAPI 将 Messages 转为 Codex 请求，使用已登录的 ChatGPT 账号推理。

Claude Code → 本机 loopback → 独立 VM 内 CLIProxyAPI → ChatGPT/Codex 账号

本包的账号接入不是 OpenAI 官方集成。官方 app-server 认证说明 允许本地或开源 app-server 集成继续使用现有认证，并明确禁止商业或托管服务使用该认证。本包通过 CLIProxyAPI 直接复用文件凭证，该具体路径未被这段说明明确覆盖；调用成功或 npm 发布都不代表获得上游许可。员工使用的账号与组织授权范围仍需另行确认，不能将个人登录凭证作为公共池或共享服务凭证。

未配置 profile 时默认 gpt-6-luna、max；配置后，普通启动、--resume <会话UUID> 与 --continue 都优先应用当前 profile 的模型和 effort，显式 --model 或 CLAUDE_CODE_MODEL 可以覆盖。仅当 profile 没有模型默认值时，恢复会话才读取原生模型选择元数据，不从历史 assistant 消息的占位模型推断。启动器显式传入本次选定模型及上下文选择器。固定 CLIProxyAPI 源版本 57bde35179ecbdca176ca8923d39cc18805774f2，源码下载校验 SHA-256。CLIProxyAPI 是本地第三方软件，推理上游直连 ChatGPT；不经过远端聚合网关。

启动与模型选择

进入你要操作的项目目录，执行：

~/.local/bin/claude-codex

0.4.8 修复交互式 /compact 尾部原生 system 通知被误认成压缩指令而返回 400 的问题；保留这些通知的完整内容，并区分历史结构与分片预算错误。0.4.7 修复重试/进度日志干扰交互界面：终端会话改写本地诊断文件，后台恢复不再覆盖输入框。0.4.6 增加普通请求 3 分钟无进展检测、默认无限停滞/空回复恢复、请求进展状态，以及默认 3 路的并行压缩。保留完整单轮回复缓冲和当前 profile 的模型/effort/上下文在 resume 时生效的支持。升级会保留现有 profile；已有进程需要退出后重新启动或 resume。包不会替员工默认开启 Ultra、812k 或 bypass，按个人 profile 配置应用。

诊断或一次性请求：

~/.local/bin/claude-codex doctor
~/.local/bin/claude-codex -p "你好"
~/.local/bin/claude-codex --model gpt-6-sol --effort max
~/.local/bin/claude-codex --model gpt-6.1-sol --effort ultra
~/.local/bin/claude-codex --model gpt-6-luna --fast

会话内用 /model 打开 GPT 菜单、/fast 切换 Fast。模型列表取代理目录与本机 Codex 可见模型缓存的交集，每次启动重新读取；本轮已实测 gpt-6-luna、gpt-6.1-sol、gpt-6-astra、gpt-6-sol、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna。目录可能更新，账号缓存里出现但代理未提供的模型不会加入菜单。

--effort ultra 是 claude-codex 的封装模式：上游推理使用原生/API 的 max 档位，通过 Claude Code 原生 Agent 工具优先并行处理可独立拆分的工作，由主会话整合和验证。简单、常规、低价值子任务使用 codex-luna-worker（gpt-6-luna / max），复杂实现、深度研究、模型评估和困难推理使用 codex-sol-worker（gpt-6.1-sol / max）。两类代理禁止递归调用 Agent。主会话规则要求执行用户已授权的工作，优先实际测试、数据和一手证据；显式 plan mode 只研究和规划。

当前请求需要结果时，默认使用前台 Agent 调用并等待工具返回；用户要求异步工作时才使用后台代理。简单请求直接执行，用户明确禁止委派时照常遵守。执行代理并发上限通过原生 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=50 设置；若父环境已有更严格的正整数上限，则保留该值；任务按需拆分，不会每次启动 50 个代理。路由与拆分由模型选择，不能保证每个任务都会委派。Ultra 合并用户的 --agents JSON，两个内置名称保留给包装器。

一次性启用也可以使用 CLAUDE_CODEX_EFFORT=ultra claude-codex。若要在独立 profile 中持久启用，在 ~/.config/claude-codex/claude/settings.json 的 env 对象内保存 "CLAUDE_CODEX_EFFORT": "ultra"；优先级为显式 --effort、当前进程 CLAUDE_CODEX_EFFORT、CLAUDE_CODE_EFFORT_LEVEL、profile 的 env.CLAUDE_CODEX_EFFORT、profile effortLevel。Ultra 与已有的 --append-system-prompt 文本会合并；为避免隐式读取文件，Ultra 不接受 --append-system-prompt-file。

启动器默认传入 --system-prompt-snapshot off，使恢复旧会话时重新生成当前规则，也让显式 --effort max 可以退出旧 Ultra 编排提示。显式传入快照选项仍优先；自行设置 on 可能继续使用旧会话快照，直到压缩。

显式用 --model 指定代理提供的其他 GPT ID 时，会保留当前模型行，即使它不在缓存的可见列表中；这类额外选择不在上述 7 模型的验收范围。开发工具所需的其他父进程环境变量会继续继承，本入口只替换已列出的 provider 凭证和路由变量。

Fast 每次启动默认关闭，只有 --fast 或本会话 /fast 才开启。开启后保留实际 GPT 型号与 effort，将 Claude 的 speed: fast 转成 Codex service_tier: priority。这表示请求优先档位，实际服务档位由上游决定，可能增加账号额度消耗。本次账号实测 priority 请求完成后仍返回 default，所以尚未证明实际加速或 priority 额度已获准；终端 “Fast mode ON” 不能作为上游加速证明。

原生 Claude 的 Fast 弹窗仍显示 Opus 名称和 Anthropic 标价，那些文案不适用于此 GPT 账号链路；真实型号以 /status 与上游请求为准。

如果希望直接输入 claude-codex，在当前终端执行 export PATH="$HOME/.local/bin:$PATH"。

安装与首次配置

员工安装推荐使用下列 macOS 流程。需要已安装 Homebrew、Node 22+、官方 Claude Code、Codex，以及 Docker CLI / Colima。此 MVP 已验证 macOS；其他平台可指定已有 Docker context，但尚未验收。

brew install node colima docker
brew install --cask claude-code
npm install --global --prefix "$HOME/.local" @openai/codex @ezerlab/[email protected]
export PATH="$HOME/.local/bin:$PATH"

上面的 PATH 设置只作用于当前终端。可在你已有的 shell 配置里加入同一行，使新终端也能找到入口；无需 sudo。确认 node --version 为 22 或更高、claude --version 和 codex --version 能正常显示。

使用自己的 ChatGPT 账号登录，选择文件凭证存储：

codex -c 'cli_auth_credentials_store="file"' login
test -f "$HOME/.codex/auth.json"
claude-codex setup
claude-codex doctor

setup 首次会下载并在独立 VM 中构建代理，可能需要数分钟，并需要 GitHub、Docker Hub 和依赖镜像的网络访问。doctor 检查工具、runtime、凭证和模型可见性；一次实际调用可用 claude-codex -p "请回复：连接正常" 验证。每名员工使用自己的账号；安装命令不需要 npm 登录。

进入项目目录启动：

cd /path/to/your/project
claude-codex

继续同一项目最近的 claude-codex 会话：

claude-codex --continue

这继续的是独立 Claude profile 的历史；原生 Codex 历史导入尚未包含在本包。模型选择和 Fast 用法见上方示例。升级只需重新运行固定版本的 npm 安装命令；同一代理 runtime 已构建时可复用。

安装方法参考 Claude Code 官方说明、Colima 安装说明 与 OpenAI Docs 的凭证存储说明。本包当前只读取文件凭证，系统 keychain 登录需要先完成上述文件登录。

setup 仅在独立 VM 中构建固定源码。启动入口不会修改默认 Docker context。Colima profile 为 claude-codex，无宿主目录挂载和 SSH agent。Claude 在本机操作当前项目，代理没有项目文件、Docker socket 或个人目录。

当前账号从 ~/.codex/auth.json 只读加载；仅当前访问凭证被投影到代理容器 tmpfs，不带有效 refresh token，不写回原凭证。每个启动使用独立容器、随机 loopback 端口和随机 client key。正常退出及 SIGTERM 删除容器与会话 settings 文件；强制 SIGKILL 后可运行 claude-codex cleanup 清理无主进程的容器。

独立 Claude profile 位于 ~/.config/claude-codex/claude，保留本入口自己的会话、信任与权限设置，不导入原 Claude profile 的插件/MCP。首次交互可能出现主题和目录信任提示。包本身不替员工开启 bypass；本机按用户要求在该 profile 设置 permissions.defaultMode: "bypassPermissions" 和 skipDangerousModePermissionPrompt: true，启动器也会在 resume 时重申这个默认模式。显式 --permission-mode、--dangerously-skip-permissions 或 --restricted 优先。

claude-codex --continue                         # 本机默认 bypass + Ultra
claude-codex --continue --permission-mode plan  # 恢复后只规划
claude-codex --permission-mode auto             # 请求原生 Auto，是否可用须实测

bypass 与 Auto 是互斥权限模式。原生 Auto 使用独立分类器审核工具调用，受原生版本、模型及 provider 支持限制；不能把接受参数或无报错当成分类器正常工作的证据。参考 Claude Code 权限模式说明。绕过本地权限提示不会授予发布、推送、部署或无关远端操作的授权。

连接恢复

默认 持续等待网络或暂时故障恢复，不限制总重试次数。链路为 Claude Code → 本机 Node 重连入口 → 隔离 CLIProxyAPI → Codex。连续模式关闭 CLIProxyAPI 内层重试及原生 Claude 的外层重试，由网关统一恢复；仅 /v1/messages 在本轮回复尚未交付时重试。等待按约 1、2、4、8、16、30 秒退避并带随机抖动，最长间隔 30 秒，每 15 秒发送 SSE 注释心跳；实际重连次数、原因与下一次等待时间通过诊断日志记录。客户端取消或退出会中止当前请求及等待。默认上游连续 3 分钟无任何数据，或普通请求连续 3 分钟没有有效内容进展，就关闭旧连接并重新发起相同请求。代理心跳只刷新传输空闲计时，不刷新普通请求的模型进展计时；本地发送的心跳不刷新两者。有效思考、签名、正文或工具参数会刷新进展计时，因此 3 分钟不是正常任务的总时长限制。完整回复缓冲尚未交付时可恢复，已经开始交付的 stream 回复报告断流并停止重放。

从 0.4.7 起，stderr 是终端时，重试、每分钟进展和压缩诊断写入配置文件同级的 logs/retry.log；默认位置为 ~/.config/claude-codex/logs/retry.log。文件权限为 0600，约 4 MiB 满后丢弃旧诊断；多进程同时写入时最多暂时增加每个写入进程的一条记录（单条上限 4 KiB），避免日志锁阻塞请求。仅记录生成的请求 ID、尝试次数和进展计数，不保存提示词、回复或凭证。诊断文件不可写时仍静默恢复；认证、配额等终止错误继续通过 API 显示在 Claude 界面。启动时只提示一次日志位置，不在界面运行期间打印后台日志。需要实时查看可在另一个终端运行 tail -f ~/.config/claude-codex/logs/retry.log。stderr 重定向到文件或管道时保留原文本诊断，stdout 不受影响。

从 0.4.2 起，持续模式还协调原生 Claude Code 的客户端超时。已测原生 2.1.274 对连续心跳设置次数上限，超过上限后即使重连入口仍然存活，也可能报 Stream idle timeout - no chunks received。启动器在子进程及临时受控 settings 中关闭这层事件超时（CLAUDE_ENABLE_STREAM_WATCHDOG=0），保留并强制启用字节失活检测（CLAUDE_ENABLE_BYTE_WATCHDOG=1）：本地入口无任何字节超过 max(30000, 3 × heartbeatMs) 毫秒时仍会报错，默认 45 秒。上游空闲检测、不可重试错误、取消及输出后不重放规则继续生效。旧有限模式不调整原生超时。这些原生环境开关已用 2.1.274 实测；其他原生版本仍需兼容性验证。

claude-codex                          # 默认持续等待恢复
CLAUDE_CODEX_RETRIES=infinite claude-codex
CLAUDE_CODEX_RETRIES=0 claude-codex    # 关闭代理重试
CLAUDE_CODEX_RETRIES=10 claude-codex   # 旧有限模式，最多增加 10 次（允许 0–10）

重试参数读取 ~/.config/claude-codex/config.json，不存在时使用默认值。它与原生 Codex config.toml、Claude profile 的 claude/settings.json 分开。可创建以下 JSON：

{
  "retry": {
    "retries": "infinite",
    "baseDelayMs": 1000,
    "maxDelayMs": 30000,
    "jitterRatio": 0.2,
    "heartbeatMs": 15000,
    "idleTimeoutMs": 180000,
    "progressTimeoutMs": 180000,
    "maxStallRetries": "infinite",
    "maxEmptyResponseRetries": "infinite",
    "statusIntervalMs": 60000,
    "delivery": "buffered"
  },
  "compaction": {
    "progressTimeoutMs": 1200000
  }
}

运行 claude-codex config 查看有效配置，无需登录或启动 Docker。CLAUDE_CODEX_CONFIG_FILE=/absolute/path/config.json 可指定其他文件；CLAUDE_CODEX_RETRIES 优先覆盖文件中的 retries。修改配置后重启或 --continue 即生效，已有进程不会热更新。配置控制恢复等待和无进展检测，不限制正常请求间隔或多个 Agent 的总 QPS。普通请求进展与无限语义恢复参数需要 0.4.6 或更新版本。

| 参数 | 允许值 | 含义 | | --- | --- | --- | | delivery | "buffered"（默认）或 "stream" | 连续模式每轮完整回复收齐后交付，或实时逐字交付；旧有限模式忽略此选项 | | retries | "infinite" 或数字 0–10 | 默认持续模式；数字使用旧 CPA 有限重试，其他等待参数不作用于旧模式 | | baseDelayMs | 整数 100–60000 | 首次失败等待毫秒数 | | maxDelayMs | 整数 100–300000，且不小于 base | 指数退避最终上限 | | jitterRatio | 0–0.5 | ±比例随机抖动，最终仍不超过上限 | | heartbeatMs | 整数 1000–60000 | 向 Claude 发送等待心跳的间隔 | | idleTimeoutMs | 整数 30000–3600000，且至少为心跳间隔两倍 | 上游无任何数据的空闲超时 | | progressTimeoutMs | 整数 30000–3600000，默认 180000 | 普通流式 Messages 连续多久没有可观察内容进展才中止本次尝试；心跳不刷新 | | maxStallRetries | "infinite"（默认）或整数 0–10 | 普通请求无进展或空握手断流的额外尝试次数；无限模式持续恢复 | | maxEmptyResponseRetries | "infinite"（默认）或整数 0–10 | 普通空 end-turn 回复的额外尝试次数；无限模式持续恢复 | | statusIntervalMs | 整数 1000–300000，默认 60000 | 普通请求的状态报告间隔 |

错误 JSON、未知字段、非法范围或显式指定的文件不存在都会报错，避免静默使用错误设置。该配置文件不应包含凭证，也不能配置上游地址或放宽输出后重放限制。

普通请求每分钟报告本地请求 ID、实际尝试次数、从代理收到的字节、内容进展事件及用量字段是否已返回。代理 HTTP 200、心跳和 input_tokens: 0 都不能证明 ChatGPT 已接受请求或模型正在推理。完整回复缓冲期间，即使已有真实内容，原生界面的 token 仍可能暂时为 0。进展检测在内存缓冲内部进行，不提前交付工具或编造用量；日志不包含提示词、正文、签名或凭证。

明确的连接失败及已识别暂时性服务错误继续恢复。普通请求连续 3 分钟无可观察内容进展就关闭本次连接，再按退避策略实际重新请求上游；心跳不刷新计时，真实内容进展会刷新。无进展、传输空闲、空握手断流和空 end-turn 回复默认不限制重试次数，持续到完成、用户取消或不可重试错误；空回复恢复也保留退避，避免高速循环。显式设置数字 0–10 仍可选择有限预算，重新连接或 ping 不清零。非常慢且没有可观察输出的合法 MAX 推理也可能触发阈值，必要时提高 retry.progressTimeoutMs。连续模式将原生 CLAUDE_CODE_MAX_RETRIES 固定为 0，由网关统一记录和执行恢复。已经开始交付的 stream 回复仍不会重放。

大上下文压缩（0.4.5）

压缩保持当前模型和推理档位，包括 max；不会降低 effort、修改当前上下文窗口、改写保留指令或静默截断输入历史。812k 是本轮本机 profile 的 Claude 侧窗口设置，不是包默认值，也不代表单个上游请求已验证能接收 812k。原生 Claude Code 2.1.274 的压缩进度按等待时间计算并封顶在 95%，不是服务端实际进度；启动器另外显示实际分段阶段和模型进展。

0.4.8 修复真实交互式压缩在用户摘要指令后追加文本 system/developer 通知时的 400。通知完整引用为摘要上下文，每段和最终合并仍使用原用户保留指令；不会越过后续 assistant/tool 回合寻找指令。2026-10-15 的原生 TUI 请求覆盖 638 条消息、321 对工具调用/结果和 1268 个思考签名，分为 4 段，完整消息重建与每段通知保留检查通过。

同日真实 ChatGPT 账号、gpt-6.1-sol / max 的隔离副本完成交互式 /compact 和独立恢复问答，整套验收用时 13 分 23.905 秒。4 段以最多 3 路并行摘要，再最终合并，没有重试；新手动压缩边界的原生估算从 926,824 降至 17,820 token，压缩自身耗时 13 分 11.436 秒。这是 Claude 侧元数据，不证明单个上游请求接收了该 token 数。摘要包含核心 learner 和多臂投机方案，恢复后一个回合返回精确 COMPACTION_CONTEXT_OK；原始会话字节未变，临时副本、代理和设置全部清理。测试关闭钩子并使用空工具/MCP，仅用于隔离验证；不保证摘要逐项保留所有语义。

2026-10-14 使用真实 Claude Code 2.1.274、ChatGPT 账号和 gpt-6.1-sol / max，在私有会话副本上完成 10 段摘要与最终合并：原生压缩元数据从 735,311 降至 18,887 token，耗时 46 分 10 秒；合并阶段发生一次暂时性失败，仅重试合并，保留已完成的 10 段。原会话校验值未变。规划检查覆盖 603 条历史消息和 47 个原类型媒体块，没有静默遗漏输入；这些检查不保证模型摘要保留每一个语义细节。

最初的整套脚本在恢复问答后失败：模型已先返回正确标记，但副本继承了旧会话的 /goal Stop 钩子，要求继续完成原研究任务，最终命令行结果为空。该失败记录保留。随后在同一个已压缩副本上，使用仅测试生效的 disableAllHooks: true 独立验证恢复：7.8 秒、一个回合返回精确的 COMPACTION_CONTEXT_OK，没有新 Stop 钩子或压缩边界，测试资源全部清理。生产启动器不会关闭用户钩子或清除目标。这是实际压缩加独立恢复验证，不是原整套脚本通过。

大压缩采用分段摘要再合并：历史按顺序分组，工具调用与结果保持成对；超过单段预算的纯文本原子记录可转成连续、可重建的历史 JSON 数据片，不执行其中的工具。默认每段历史预算 256000 个可见字符、8 MiB JSON 和 8 个媒体块；超过 512000 可见字符、8 MiB 或 8 个媒体块时启用。图像/文档及加密思考保持原类型，不将编码数据当成提示词。一个工具结果内的媒体序列可独占一段，最多 32 个媒体块且仍遵守字符/字节预算；超大的带媒体或加密签名的原子记录会在推理前明确返回错误，不转为文字或静默截断。历史系统通知作为数据保留。所有段和最终合并继承原模型、thinking、effort 和自定义保留指令。

完整有效的段摘要只缓存在本进程内存中；断流只重试失败段，最终合并成功后才向 Claude Code 交付一次结果。中间段不会写入原生会话或触发工具；退出进程会丢失这些检查点。公共 0.4.5 顺序执行各段。分段会增加请求次数、重复提示词和账号额度消耗，MAX 下仍可能等待数十分钟。大压缩即使设置 delivery: "stream" 也按完整结果交付，以保护中间摘要。最终 token 用量包含成功完成的段与合并，失败尝试的上游消耗可能无法统计；原生 Anthropic 标价字段不代表 ChatGPT 账号的实际账单。生产继续使用固定的原始 HTTP 上游，不默认启用实验性 WebSocket 路径。

0.4.6 默认同时总结最多 3 个独立片段，再按原始片段顺序合并；完成顺序不会改变历史顺序。每个片段独立检测进展并重试，已完成的其他片段保留。取消、不可重试错误或缓冲超限会中止并行任务，释放其资源，不向原生会话交付中间摘要。全部片段与合并继续使用原模型和 effort。诊断状态包含真实阶段、已完成/总片段数和活动请求数；原生的 95% 时间进度条仍由 Claude Code 控制。

可在 ~/.config/claude-codex/config.json 的 compaction 中配置 "concurrency": 3，允许整数 1–4；1 恢复串行行为。现有 progressTimeoutMs 可以同时保留。这是每次压缩的并发数，多个 Claude 进程会各自使用自己的并发额度。更高并发会提高瞬时请求量和内存占用，速度受上游负载与账号限制影响，不能保证倍数加速。0.4.5 及更早版本不接受该字段。

默认连续模式启用原生 gateway hint headers，按 x-claude-code-compaction 或 compaction request class 识别压缩。除传输空闲检测外，压缩单独检测模型进展：注释、ping、空握手和空内容头不能重置此计时器；非空文字、思考、加密签名和工具参数可重置。默认 20 分钟没有模型进展时中止本次上游尝试，保持当前段正文和原推理档位，按原连续策略重试。它不限制压缩总时长，也不是强制压缩期限；非常慢且不输出进展的合法思考也可能被重试，可将 compaction.progressTimeoutMs 调高。允许范围 30000–3600000 毫秒。每分钟额外显示压缩等待、上次模型进展和尝试次数，客户端取消仍停止等待。旧有限模式不启用此入口。

固定代理在关闭正常请求日志时仍会进行临时的错误日志捕获。其大请求捕获上限为每次 32 MiB，原来与凭证/配置共享的 16 MiB tmpfs 会被长上下文请求填满；捕获写入失败不会直接截断上游请求，因此不能据此单独认定压缩挂起的根因。本地修复将运行状态和日志放到独立的 128 MiB tmpfs，保留原 16 MiB 凭证/配置区域，错误日志最多保留两个。它仍是有界的内存存储，大量并发时日志区域也可能达到上限；退出后整个容器删除，不使用宿主持久日志卷。

仓库内原生压缩验证（在 packages/claude-codex 目录执行，本地合成上游，不消耗账号额度；测试脚本不随 npm 包分发）：

node test/compaction-native-integration.mjs --isolated
node test/compaction-native-integration.mjs --isolated --hierarchical
node test/compaction-native-integration.mjs --isolated --hierarchical --fragmented
node test/compaction-native-integration.mjs --isolated --hierarchical --fragmented --parallel

该验证运行真实 Claude Code 的 seed → /compact → resume，注入只有心跳的停滞，检查实际重试、两次压缩请求逐字节一致、max 和保留指令不变、仅一个压缩边界以及恢复后的摘要保留。分段模式还检查第一段完成后第二段停滞，只重试第二段，并且只交付一个最终摘要。它不能代替大上下文的真实账号验证。

网络连接失败、HTTP 408/500/502/503/504，以及交付前明确的暂时性 SSE 错误可恢复。认证、权限、配额/限流、无效参数等不可重试错误会停止；HTTP 400/401/403/404/413/429 不持续重试。其他接口与未知 SSE 错误不会无限重放。连续模式将原生 CLAUDE_CODE_MAX_RETRIES 固定为 0，避免外层重试乘上网关的恢复次数；旧有限模式保留原生设置。

默认 delivery: "buffered" 将本轮完整 Messages 回复（包括文字、思考签名和工具参数）暂存在内存，收到有效的 message_stop、结束原因且所有内容块关闭后才一次交付给 Claude。因此，即使上游已经生成文字或完整工具参数，只要回复尚未完整交付，暂时性断流仍会丢弃失败尝试并重试；Claude 不会执行这些失败尝试的工具。每轮完成后立即交付并继续下一步工具/任务，不缓存整个开发任务。代价是本轮文字不逐字显示，等待期间仍有心跳并可取消。每响应最多 16 MiB、每入口合计 128 MiB、单 SSE 帧最多 1 MiB；超限或异常协议明确报错并停止，不无限重试。不会把响应缓存写入磁盘。完成后的下游交付一旦开始，不因下游断开而重放。

显式设置 delivery: "stream" 可恢复实时显示。此模式暂存空的 message_start、空 text 块头和严格匹配的、尚无可见思考文字的 thinking 块及加密签名，忽略心跳。签名只在内存私下暂存，不会丢弃或修改：本次尝试成功产生可见输出时按原顺序交付；此前断流则丢弃未交付的本次尝试并持续重试。任何非空思考/文字、工具开始事件、异常格式或未知事件一旦交付，就停止自动重放该请求。签名暂存与 SSE 帧合计最多 1 MiB，超限明确报错并停止重试，避免无限内存增长。断流或缺少 message_stop 时返回明确 SSE 错误，不伪造完成，不重启整个 Claude 进程。这不是流内容续传，也不能保证端到端工具恰好执行一次。模型可能已接收请求、开始计算但尚未输出，因此输出前重试仍可能增加账号消耗；服务永久不可用会一直等待，须主动取消。凭证在长时间等待中可能过期，本入口不刷新凭证，需使用 Codex 更新登录后重新启动。

Node 重连入口的请求体只在内存暂存，最多 64 MiB。默认完整回复缓存上限为每请求 16 MiB、每入口合计 128 MiB；实时模式的握手、空内容头及未交付加密思考合计最多 1 MiB，单 SSE 帧也最多 1 MiB。该入口不记录提示词、响应正文或凭证；固定代理自身可能进行错误日志临时捕获，见压缩修复说明，其状态不挂载到宿主持久存储。重连入口仅监听 127.0.0.1，验证每会话随机密钥，只访问固定本地上游且不跟随重定向。新默认对 重启后的进程 生效，已有会话可退出后使用 claude-codex --continue 恢复。这些功能从 0.4.0 起提供；旧 0.3.3 不包含此连续重连机制。

不再设置 ANTHROPIC_MODEL、CLAUDE_CODE_SUBAGENT_MODEL 或 CLAUDE_CODE_SUBAGENT_MODEL_FORCE，并清理父进程继承的这些固定值。普通执行子代理未指定模型时遵循原生继承规则，随当前主模型运行；显式指定模型的代理仍保留自己的选择。Opus/Sonnet/Haiku/Fable 和小型辅助请求的别名仍映射到本次启动选定的 GPT 模型，避免把 Claude 型号发给 Codex；这些辅助请求与主对话、默认继承的执行子代理分别核验。菜单的兼容能力声明让原生 effort 与 Fast 开关可用，发送的模型 ID 始终是 GPT；它不代表两家模型具备相同能力。自动压缩窗口优先使用独立 profile 中有效的 autoCompactWindow（100000–1000000），否则按可见 Codex 缓存中的最小窗口设置；启动参数 --autocompact 仍可显式覆盖。当配置窗口或模型目录窗口超过 200k 时，启动器和模型菜单使用原生 [1m] 上下文选择器，Claude 会在 API 请求前去掉这个后缀，实际 GPT 模型 ID 不变。此选择器覆盖真实交互终端和 --resume / --continue 恢复；仅传 --betas 在此原生版本中只能修复 -p 路径。已有进程可运行 /model gpt-6.1-sol[1m] 再用 /context 检查；直接手输不带 [1m] 的 /model 型号会选回原生 200k 上限，可从模型菜单选择或显式保留后缀；窗口仍包含原生预留的输出/压缩缓冲区，并不保证在恰好相同数量的输入 token 时才压缩。本轮的长会话压缩与恢复验证范围见上文，不代表所有长输入场景均已验收。--settings、--setting-sources、--fallback-model 由本入口管理，避免覆盖路由；其他常用 Claude 参数透传。

本机缓存目前将 gpt-6.1-sol 和 gpt-6-luna 的上下文标为 272000。812k 已验证的是 Claude 侧窗口配置与 /context 显示；本轮另验证了 735,311-token 私有副本的分段压缩及独立恢复问答，不能据此保证单个上游请求接受 812k 输入或恰好满窗口的行为。

MVP 边界

• 只支持 Codex ChatGPT 的文件凭证；系统 keychain 模式尚未接入。
• 访问凭证过期时，使用官方 Codex 更新登录再启动；本入口不自动刷新。
• 原 Claude profile 的插件/MCP 和跨 profile resume 未在本轮验收。长会话压缩与独立恢复问答的已测范围及钩子隔离见上文，不保证全部历史细节无损保留。
• 旧 app-server 实验入口保留在 bin/claude-codex-app-server.mjs 供回滚，未作为 fallback，也不包含在 npm 包内。
• 0.4.8 识别交互式压缩指令之后的文本 system/developer 通知，完整保留为摘要上下文；保持历史工具链、媒体、思考签名和 MAX，结构错误与预算错误返回独立的脱敏原因码。
• 0.4.7 将终端会话的重试、普通进展和压缩诊断写入有界本地日志，修复与原生界面重绘互相覆盖；重试、取消和错误返回行为不变。
• 0.4.6 增加普通请求 3 分钟无进展检测、默认无限停滞/空回复重试和请求状态；统一恢复层，默认 3 路并行压缩并保持历史顺序与 MAX。
• 0.4.5 增加顺序分段摘要与合并、阶段检查点、压缩模型进展检测、明确的规划错误提示和独立日志 tmpfs；保持当前模型、推理档位、保留指令及固定 HTTP 传输。
• 0.4.4 保留 0.4.3 的重连实现，补充真实账号持续断流 3 分钟的验证说明，并扩展仓库内故障测试的持续中断参数。
• 0.4.3 默认按完整单轮回复交付，覆盖生成部分文字/工具参数后、完成前的断流重试；修复实时模式把空 text 块头提前交付的问题。启动信息和 config 显示启动器版本与有效交付模式。
• 0.4.1 修复 0.4.0 把 signature-only thinking 提前交付的问题：长思考尚无文字或工具时断流可以持续重试，成功尝试的签名原样保留。已输出可见思考、文字或工具事件的请求仍不会盲目重放。
• 0.4.2 修复持续模式被 Claude 的连续心跳次数上限中断的问题；保留有界的本地字节失活检测。需要升级启动器并退出、恢复原会话，单改重试配置不能修复旧启动器的行为。
• 0.4.0 增加默认持续重连、可配置退避/心跳/空闲超时及 config 查看命令，并包含 resume/上下文与 Ultra 支持。
• 0.3.3 取消主模型和默认执行子代理的启动固定，读取已保存的模型选择；保留 0.3.2 的重试、SSE 心跳和输出前握手暂存。历史导入会话的占位模型元数据不在本次修复范围。

验证

npm test
npm run pack:check

在源码仓库的 packages/claude-codex 目录执行真实账号持续断流验证（需要已构建 Docker runtime、Claude Code 和已有 Codex 文件登录，会消耗账号额度；测试脚本不随 npm 包分发）：

node test/real-buffered-fault.mjs --account --inject-one-fault --outage-ms=180000

还可验证“实际工具事件后只剩心跳，再等待 3 分钟连接恢复”：

node test/real-buffered-fault.mjs --account --inject-one-fault --heartbeat-stall --outage-ms=180000

该故障只作用于测试自己的 loopback relay，不关闭主机网络。它使用真实账号、gpt-6.1-sol / max 和临时 Bash 计数文件；测试进展阈值直接使用正式默认的 3 分钟。检查新上游请求实际到达、重放正文校验值一致、旧停滞连接关闭、恢复后计数只增加一次及最终回答。每次脚本最多转发 16 个真实账号请求，超出会停止，不自动重跑整个测试；此限制只用于隔离测试。

0.4.6 发布前实测：真实上游已生成工具事件后，中继只发送心跳；无进展检测在 179.969 秒触发，旧连接关闭，相同请求正文重新到达上游，最终回答成功，Bash 计数恰为一次。整个样例耗时 248.927 秒。首次样例遇到 4 次 HTTP 503 后耗尽原 6 次测试调用预算，最终回答失败，该失败保留；将测试预算调整为 16 次后受控补测通过，实际转发 3 个请求。原生 Claude 加固定代理的隔离测试另覆盖连续 13 次停滞及 13 次空回复后恢复，各自只执行一次工具。这些样例不保证所有网络故障或任务都能恢复。

2026-10-13 使用真实 Claude Code 和 gpt-6.1-sol[1m] 验证：生成工具参数后断开测试中继，持续拒绝连接 180.003 秒；网关记录 11 次重试，恢复后 28.070 秒自动发出下一次请求，全程 248.506 秒后成功完成。中断和恢复瞬间计数文件均不存在，最终内容恰为 x，验证没有重复追加。使用默认 1–30 秒退避、15 秒心跳、300 秒上游空闲超时、完整单轮回复缓冲；测试运行时模块与已安装的 0.4.3 一致，0.4.4 未改变这些模块。测试只影响隔离中继，不关闭整机网络；这一结果覆盖单个顺序客户端的持续连接断开，不能据此保证所有丢包、DNS/TLS 或并发故障都能恢复，也不是逐个工具调用的独立审计。

隔离代理故障注入验证（需要已构建 Docker runtime，使用本地测试上游，不消耗模型额度）：

node test/reconnect-integration.mjs --isolated
node test/reconnect-integration.mjs --isolated --continuous
node test/reconnect-integration.mjs --isolated --continuous --buffered
node test/recovery-native-integration.mjs --isolated
node test/idle-timeout-integration.mjs --isolated
node test/idle-timeout-integration.mjs --isolated --long

第一条检查旧有限模式；第二条检查默认连续模式，覆盖 13 次失败后第 14 次恢复、仅有加密思考后断流/EOF 的持续恢复、原生 Claude CLI 接收恢复后的 SSE、响应前/握手后断线、503 恢复、部分文本/工具事件不重放及取消等待。连续模式 fixture 从临时配置文件读取加速的退避和心跳间隔，生产默认仍为 1–30 秒退避与 15 秒心跳。此检查运行实际固定版本的代理，测试上游是合成 fixture；不等于真实账号在实际断网后的完整 Claude 工具执行验收。

后两条直接运行原生 Claude 与本地 Messages fixture：短检查覆盖私有思考等待、取消、失活入口的 30 秒检测；--long 并行对照修复前与修复后客户端，实际等待 640 秒，跨越原生五分钟事件超时和连续心跳宽限。无需真实凭证或公共模型请求，也不会修改用户会话。测试心跳为一秒，生产默认仍为十五秒。

从仓库根目录运行真实代码任务验证：

npm run test:claude-codex:e2e

多模型、原生 Read/Bash、Fast 请求字段与真实上游返回档位验证（消耗账号额度）：

node packages/claude-codex/test/model-fast-e2e.mjs --live

它使用真实 Claude Code 和账号上游，在一次性 Git fixture 内验证原生 Read/Edit/Bash、源码修复、回归测试、保护文件与退出清理。单元测试中的 synthetic fixtures 不能替代 live 结果。

维护者发布

本包采用 GitHub Actions + npm Trusted Publishing（OIDC），不在工作流中保存 npm token。.github/workflows/publish-claude-codex.yml 在 PR 时运行包测试和打包检查；源码合入 main 后，推送与 package.json 版本一致的 claude-codex-v<版本> 标签触发发布。手动运行工作流仅验证，不发布。

npm 包设置需先绑定 GitHub owner Joey-Lei、repository ezer-api-gateway、workflow filename publish-claude-codex.yml，允许直接 npm publish，environment 留空。首次绑定需要维护者登录和二次验证；每次 CI 发布使用短期 OIDC 身份。核对 registry 版本与完整性后再宣布发布完成。当前源码仓库为私有仓库，因此显式关闭 provenance；这不影响使用 OIDC。参见 npm Trusted Publishing 官方说明。

CI 使用 Node 24 和固定 npm 11.21.0；员工运行环境仍为 Node 22+。发布前校验包名、仓库、精确版本标签及提交属于 main 历史，并检查 tarball 只包含允许的运行文件；发布的是该已检查的 tarball。

许可证

本包以 MIT 许可证发布，完整条款随包内 LICENSE 分发。第三方 CLIProxyAPI 的许可证声明保留在 runtime/CLIProxyAPI-LICENSE。

完整回复模式另验证部分文字/工具参数后断流的恢复、13 次失败后第 14 次交付、协议终止验证与内存总量限制。recovery-native-integration 使用实际固定代理和原生 Claude 的 Bash/Agent 工具，测试失败尝试不执行工具、成功恢复只执行一次及原生子 Agent 的重试路由；使用本地合成上游，不消费真实账号额度。启动时应看到 claude-codex v0.4.8: delivery=buffered, retries=infinite。旧进程不热更新，退出后 claude-codex --resume 应用；claude-codex config 可确认包版本与有效 delivery。