ccodex-sleep-state 教程：可视化接管 Codex、配置代理并排查连接问题

项目简介

ccodex-sleep-state 是一个用 Go 编写的本地工具，目标是改善 Codex 使用过程中可能出现的回答质量变化、限流、连接失败和配置冲突问题。它把连接管理、代理出口、turn-state 采集、配置接管和故障诊断集中到一个本地服务与网页面板中，减少手工修改配置文件的需要。

需要先明确：该工具不会增加账号额度，也不能保证更换出口后模型质量一定恢复。它处理的是连接、配置和响应中的 X-Codex-Turn-State，让采集结果、注入状态、请求路径和错误原因更容易检查。

项目目前仍是公开测试版。不同 Release 的功能可能不同，应以所下载版本的发布说明为准，不能把部分模型或压缩流程测试成功理解为所有场景均已验收。

核心功能

• 本地网页面板：查看 Codex 是否已接管、请求是否经过服务、会话情况和请求计数。
• turn-state 采集与注入：从候选出口发送短请求，检查响应中的 state，并在后续请求中按规则使用。
• 多种认证方式：分别处理官方 ChatGPT 登录、OpenAI 官方 API key，以及 Responses 中转或 CCS API key。
• 模型隔离：支持 gpt-6-astra、gpt-5.6-sol 和 gpt-5.6-terra；state 按账号、凭据和模型隔离，不跨模型混用。
• 代理与订阅：支持 HTTP、HTTPS、SOCKS5，以及 Clash/Mihomo YAML、逐行 URI 和 Base64 URI 订阅。
• 配置保护：接管前备份 Codex 配置，停止服务时尝试恢复；配置损坏时可进入修复面板。
• 诊断能力：可下载脱敏诊断，或运行 doctor 命令收集排错信息。

安装前准备

首先确认 Codex 在不经过本工具时原本可以正常使用。官方账号需要先完成登录；使用中转服务时，应先配置好自己的 API key。

如果同时使用 CCS 或 CC Switch，请先在其中选好本次需要使用的 provider、上游和认证配置，然后退出 Codex，并暂时停止切换配置。ccodex-sleep-state 不接管 CCS 的账号数据库，只读取 Codex 当前选择的 provider，并临时将入口接到本地服务。

选择正确的安装包

1. 打开项目的 Releases 页面。
2. 普通 Windows 电脑选择 windows-amd64。
3. Windows ARM 设备选择 windows-arm64。
4. Apple 芯片 Mac 选择 darwin-arm64。
5. Intel Mac 选择 darwin-amd64。
6. 下载后完整解压，不要只从压缩包中直接运行单个文件。

启动与初始化

使用启动脚本

Windows 用户双击 start.cmd，macOS 用户双击 start.command。服务启动后，浏览器通常会自动打开本地管理面板，并直接进入当前会话，无需预先复制管理口令。

程序会创建缺失的服务配置、备份并接入 Codex。看到面板显示已经接管后，应重启 Codex 并新建会话，然后发送一条短消息测试。旧会话不会被热切换，因此不要只在原会话中继续测试。

使用命令行启动

如果发布包中没有启动脚本，可在程序目录中执行 setup。Windows 命令如下：

.\ccodex-sleep-state.exe setup

macOS 命令如下：

./ccodex-sleep-state setup

setup 会创建缺失配置、启动服务并打开面板，不会重置已经保存的订阅和代理设置。旧版本如果不支持该命令，应先升级到较新的 Release。

如果浏览器没有自动打开，请根据终端输出手动访问管理地址。默认地址为 http://127.0.0.1:17841/admin/，然后粘贴终端显示的本次管理口令。

启动程序本身不会发送模型请求，但接入 Codex 后进行 state 采集可能消耗实际额度。服务运行期间应保留终端窗口。

完成第一次接入

1. 进入面板的“开始使用”区域，确认配置状态显示已接管。
2. 如果没有检测到代理，打开“订阅与代理”，填写本地 HTTP、HTTPS 或 SOCKS5 地址，或者导入远程订阅及本地订阅文件。
3. 在“连接设置”中确认模型和账号规则。
4. 根据需要在“turn-state 注入”中开启或关闭注入。
5. 重启 Codex，并创建一个全新会话。
6. 发送一条简短消息，然后回到面板检查请求计数、会话和采集诊断。

首次运行且没有明确设置兜底策略时，setup 默认采用“采不到 state 时正常转发”。如果以前明确选择过严格模式，该选择会继续保留。

首页的“一键接入 Codex”主要用于重新检查和修复接入，不是每次启动后都必须点击。已有代理、订阅、模型和注入开关也会保留。

理解 turn-state、292 与 332

工具关注上游响应中的 X-Codex-Turn-State。它会从候选出口发送短请求，检查 state 的封装、时间和密文块数，保存符合当前经验规则的值；后续请求会携带该值，并使用与它对应的出口。

• 个人账号规则：项目接纳的经验形状是 10 块，通常为 292 字符；11 块或 312 字符不会被当作合格值。
• Team 或 Business 规则：项目接纳的经验形状是 12 块，通常为 332 字符；13 块或 356 字符不会被当作合格值。

这些长度不是 OpenAI 官方公布的质量指标。符合长度不能证明模型一定处于所谓“满血”状态，不符合也不能单独证明代理损坏或模型质量下降。

自动识别会参考当前请求中的套餐提示，而不会仅凭长度把账号判断为 Team。提示不明确时，面板会说明采用的规则；也可以手动指定个人或 Team。

选择严格模式或普通转发兜底

严格模式

严格模式不会使用不合格的 state。采集失败时，请求会返回明确原因。如果用户已经明确选择 strict，后续运行 setup 不会自动覆盖。

普通转发兜底

普通转发兜底会在没有可用 state 时停止注入，但仍使用选定出口转发正式请求。正式请求最多转发一次，状态信息会明确说明此次没有注入，而不会伪装成采集成功。

该模式不等于解除限流。遇到 401、403 或 429 时，服务仍会遵守停止规则；已经发送到上游的正式生成请求不会更换出口后自动重放。

配置代理与订阅

如果已经安装代理软件，可以在“订阅与代理”页面填写本机 HTTP、HTTPS 或 SOCKS5 地址。首次自动接入只会检查 127.0.0.1 上常见的 SOCKS5 端口，不扫描局域网，也不会读取代理软件的账号数据库。

项目还支持 Clash/Mihomo YAML、逐行 URI 和 Base64 URI 订阅。内嵌出站适配包括 AnyTLS、SS、SSR、VMess、VLESS、Trojan、Hysteria、Hysteria2 和 TUIC，但不会导入订阅中的 TUN、DNS 或系统规则。

可在“路由”页面测试连接、固定出口或恢复自动选择。需要注意，连接测试成功只表示网络路径可用，并不表示已经采集到合格 state。

与 CCS 和中转服务配合使用

对于官方 ChatGPT 登录，工具可以采集并注入 state，也允许关闭注入。对于 OpenAI 官方 API key，则按 API 通道转发，不会将其当作 ChatGPT 订阅登录。

对于 Responses 中转或 CCS API key，工具会保留原有上游和 API key 认证方式，不向中转发送官方登录凭据，也不注入官方 state。

如果 CCS 真正切换了 provider、上游或认证方式，服务会停止转发，以避免把凭据发送到错误的目标。推荐采用以下切换顺序：

1. 停止 ccodex-sleep-state。
2. 在 CCS 中切换配置。
3. 重新启动 ccodex-sleep-state。
4. 重启 Codex 并新建会话。

如果出现配置冲突，不要删除事务文件，也不要盲目手改 TOML。应进入“检查与修复配置”，先预览变更，优先保留 CCS 当前配置，再重新接管。

停止服务与恢复配置

服务运行时，应保留终端窗口。需要退出时，在终端按 Ctrl+C，等待配置恢复完成，然后再重启 Codex。

关闭浏览器、关闭 state 注入和停止服务是三个不同操作：关闭浏览器不会停止后台服务；关闭注入仍可能继续转发请求；只有结束服务进程才会进入停止和配置恢复流程。

常用故障排查

面板显示“未接管”

服务启动不代表 Codex 已完成接入。按照面板中的配置提示处理，并确认没有使用只读的 --no-config 模式。

Codex 能回复，但面板没有请求

先重启 Codex并新建会话。如果仍没有记录，检查 Codex 是否使用了另一份配置、profile、项目或任务级覆盖，或者是否同时运行了另一个实例。

出现 codex_config_changed 或 409

打开“检查与修复配置”，预览差异，优先保留 CCS 当前配置，然后重新接管。

出现 state_unavailable 或本地 503

检查账号规则、采集诊断与冷却时间。需要先恢复使用时，可以明确选择普通转发兜底，或者暂时关闭注入。

出现 state_shape_changed

这表示 state 的形状与当前规则不一致。正式请求可能已经消耗额度，服务不会自动重放。应检查账号规则、上游和近期变化，而不是简单修改长度规则。

出现 415

新版支持官方客户端的 gzip 和 zstd 请求编码。确认没有运行旧版本，然后查看脱敏诊断。

出现 502、503 或超时

检查代理出口和上游服务状态。网络故障不能通过修改 state 长度解决。

出现 401、403 或 429

分别检查登录状态、访问权限或等待限流恢复。项目不会通过不断切换 IP 来绕过这些停止条件。

配置文件损坏

如果服务 JSON 损坏，setup 会打开只读修复面板。确认备份后再重建并重新启动。如果 Codex TOML 损坏，应先保留备份，再使用明确的重建流程或让 CCS 重新生成，不要从损坏文件中猜测 API key。

使用 doctor 收集诊断

向维护者、群友或 AI Agent 提供排查信息前，Windows 用户可以运行：

.\ccodex-sleep-state.exe doctor

macOS 用户运行：

./ccodex-sleep-state doctor

反馈时通常提供操作系统、Codex 版本、工具版本、错误提示和必要的脱敏诊断即可。不要发送 auth.json、管理口令、完整订阅链接、账号凭据或整个数据目录。

高级使用技巧

确认实际配置目录

如果设置过 CODEX_HOME，工具会跟随该位置。它还支持 CCODEX_STATE_HOME 和 --data-dir。不确定当前使用哪份配置时，应运行：

ccodex-sleep-state paths

不要只根据目录名称猜测当前配置位置。

理解采集成本和冷却

state 采集会使用真实额度。默认每轮最多尝试 6 个候选出口，单次探测最多 20 秒，两轮采集至少间隔 180 秒。正常生成请求不会自动重放，因此不要把采集或切换出口理解为无成本重试。

按模型和账号隔离

不要在 Astra、Sol 和 Terra 之间复用 state。修改默认模型后，应重启 Codex 或新建会话。模型是否真的可调用，仍取决于账号权限和上游是否提供对应模型。

谨慎判断压缩支持

项目记录显示，真实 Sol 的新版 V2 远程压缩及压缩后继续回复已经成功；旧式 V1 直连上游返回 404。发送前桥接只完成了本地模拟客户端测试，追加真实验收时还出现过出口传输失败，因此不能认为所有压缩方式都已跑通。

重要限制与安全边界

• 当前支持的模型仅包括 gpt-6-astra、gpt-5.6-sol 和 gpt-5.6-terra。
• 目前使用 Responses HTTP 与 SSE，不支持 WebSocket，也不提供任意协议转换。
• 工具不会替账号开通模型权限，也不会静默替换模型。
• 它不切换系统代理、不刷新 Codex 登录，也不使用重置卡。
• 中转服务能够连接，不代表 turn-state 思路对该中转有效。
• 认证值和完整 state 不会写入常规日志，项目没有遥测，也不会把日志上传给作者。
• 本地代理配置和恢复备份仍可能含有敏感信息，需要自行妥善保管。

开发者信息

项目使用 Go 编写，静态管理页嵌入二进制，不需要单独启动前端服务。主要代码结构包括：

• cmd/ccodex-sleep-state：命令、一键入口和诊断。
• internal/codexconfig：provider 解析、配置接管、语义检查和可恢复修复。
• internal/gateway：模型与账号隔离、采集、压缩和流式转发。
• internal/turnstate：state 封装规则、当前值和备用值。
• internal/proxyroute：订阅解析和出站连接。
• internal/service：单实例、网页面板、配置热切换和请求诊断。

项目采用 GPL-3.0 许可证，代理部分复用了 Mihomo。该项目与 OpenAI、Mihomo 和 GPT-Load 均无隶属关系。

总结

ccodex-sleep-state 的核心价值不是承诺解除限流或恢复模型质量，而是把 Codex 的接入、代理出口、turn-state、配置备份和错误诊断变得可见、可检查、可恢复。首次使用时，建议先验证原始 Codex 可用，再运行 setup，通过面板确认接管，重启 Codex并新建会话。遇到问题时优先查看面板诊断并运行 doctor，不要盲目修改配置或泄露敏感凭据。