ccodex-sleep-state Tutorial: Visually Manage Codex, Configure Proxies, and Troubleshoot Connection Issues

Project Overview

ccodex-sleep-state is a local tool written in Go, designed to address possible response quality changes, rate limiting, connection failures, and configuration conflicts during Codex use. It consolidates connection management, proxy exits, turn-state collection, configuration takeover, and troubleshooting into a local service and web panel, reducing the need to manually edit configuration files.

First, it is important to clarify: this tool does not increase account quotas, nor can it guarantee that model quality will recover after changing the network exit. It handles connections, configuration, and X-Codex-Turn-State in responses, making it easier to inspect collection results, injection status, request paths, and error causes.

The project is currently still in public beta. Features may differ between Releases. Refer to the release notes for the version you downloaded. A successful test with some models or compressed request flows must not be interpreted as acceptance for every scenario.

Core Features

• Local web panel: View whether Codex has been taken over, whether requests pass through the service, session status, and request counts.
• turn-state collection and injection: Send short requests through candidate exits, check the state in responses, and use it in subsequent requests according to the rules.
• Multiple authentication methods: Handle official ChatGPT login, official OpenAI API keys, and Responses relay or CCS API keys separately.
• Model isolation: Supports gpt-6-astra, gpt-5.6-sol, and gpt-5.6-terra; state is isolated by account, credential, and model and is not shared across models.
• Proxies and subscriptions: Supports HTTP, HTTPS, SOCKS5, as well as Clash/Mihomo YAML, line-by-line URI, and Base64 URI subscriptions.
• Configuration protection: Backs up the Codex configuration before takeover and attempts to restore it when the service stops; a repair panel is available when the configuration is damaged.
• Diagnostics: Download sanitized diagnostics or run the doctor command to collect troubleshooting information.

Preparation Before Installation

First confirm that Codex works normally without this tool. Official accounts must complete login first; when using a relay service, configure your own API key beforehand.

If you also use CCS or CC Switch, first select the provider, upstream, and authentication configuration needed for this session, then exit Codex and temporarily stop configuration switching. ccodex-sleep-state does not take over CCS's account database. It only reads the provider currently selected by Codex and temporarily routes the entry point to the local service.

Choose the Correct Package

1. Open the project's Releases page.
2. For standard Windows computers, choose windows-amd64.
3. For Windows ARM devices, choose windows-arm64.
4. For Apple silicon Macs, choose darwin-arm64.
5. For Intel Macs, choose darwin-amd64.
6. Fully extract the download. Do not run only a single file directly from the archive.

Starting and Initial Setup

Use the Startup Script

Windows users can double-click start.cmd; macOS users can double-click start.command. After the service starts, the browser will usually open the local management panel automatically and enter the current session directly, without requiring you to copy a management token in advance.

The program creates missing service configuration, backs up Codex, and connects to it. After the panel shows that takeover is complete, you should restart Codex and create a new session, then send a short message to test. Existing sessions are not hot-switched, so do not continue testing only in the original session.

Use the Command Line

If the release package does not include a startup script, run setup in the program directory. On Windows:

.\ccodex-sleep-state.exe setup

On macOS:

./ccodex-sleep-state setup

setup creates missing configuration, starts the service, and opens the panel. It does not reset saved subscriptions or proxy settings. If an older version does not support this command, upgrade to a newer Release first.

If the browser does not open automatically, manually visit the management address shown in the terminal. The default address is http://127.0.0.1:17841/admin/, then paste the management token displayed in the terminal for this session.

The startup program itself does not send model requests, but state collection after connecting Codex may consume actual quota. Keep the terminal window open while the service is running.

Complete the First Connection

1. Open the panel's “Get Started” section and confirm that the configuration status shows takeover is complete.
2. If no proxy is detected, open “Subscriptions and Proxies” and enter a local HTTP, HTTPS, or SOCKS5 address, or import a remote subscription or local subscription file.
3. Confirm the model and account rules under “Connection Settings.”
4. Enable or disable injection under “turn-state Injection” as needed.
5. Restart Codex and create a completely new session.
6. Send a short message, then return to the panel to check request counts, sessions, and collection diagnostics.

On the first run, when no fallback strategy has been explicitly configured, setup defaults to “forward normally when state cannot be collected.” If strict mode was explicitly selected previously, that choice is retained.

The “Connect Codex with One Click” option on the home page is mainly for rechecking and repairing the connection; it does not need to be clicked after every startup. Existing proxies, subscriptions, model settings, and injection switches are also retained.

Understanding turn-state, 292, and 332

The tool monitors X-Codex-Turn-State in upstream responses. It sends short requests through candidate exits, checks the state's format, timing, and number of encrypted blocks, and saves values that match the current empirical rules. Subsequent requests carry that value and use the exit associated with it.

• Personal account rule: The empirical format accepted by the project has 10 blocks, typically 292 characters; 11 blocks or 312 characters are not treated as valid values.
• Team or Business rule: The empirical format accepted by the project has 12 blocks, typically 332 characters; 13 blocks or 356 characters are not treated as valid values.

These lengths are not quality metrics published by OpenAI. Matching the length does not prove that the model is in a so-called “full-strength” state, and a mismatch alone does not prove that the proxy is broken or that model quality has declined.

Automatic detection considers the plan information in the current request rather than identifying an account as Team based only on length. When the information is unclear, the panel explains which rule is being used; you can also manually specify Personal or Team.

Choose Strict Mode or Normal Forwarding Fallback

Strict Mode

Strict mode does not use invalid state. When collection fails, the request returns a clear reason. If the user has explicitly selected strict, subsequent runs of setup will not overwrite it automatically.

Normal Forwarding Fallback

Normal forwarding fallback stops injection when no usable state is available but continues forwarding official requests through the selected exit. An official request is forwarded at most once. The status clearly indicates that no injection occurred this time rather than presenting it as a successful collection.

This mode does not remove rate limits. For 401, 403, or 429 responses, the service still follows the stop rules; an official generation request already sent upstream is not automatically replayed through another exit.

Configure Proxies and Subscriptions

If proxy software is already installed, enter the local HTTP, HTTPS, or SOCKS5 address on the “Subscriptions and Proxies” page. Automatic initial connection only checks common SOCKS5 ports on 127.0.0.1; it does not scan the local network or read the proxy software's account database.

The project also supports Clash/Mihomo YAML, line-by-line URI, and Base64 URI subscriptions. Built-in outbound adapters include AnyTLS, SS, SSR, VMess, VLESS, Trojan, Hysteria, Hysteria2, and TUIC, but TUN, DNS, or system rules in subscriptions are not imported.

You can test the connection, pin an exit, or restore automatic selection on the “Routing” page. Note that a successful connection test only means the network path is available; it does not mean that a valid state has been collected.

Using CCS and Relay Services

For official ChatGPT login, the tool can collect and inject state, and injection can also be disabled. For official OpenAI API keys, it forwards through the API channel and does not treat them as ChatGPT subscription logins.

For Responses relays or CCS API keys, the tool retains the existing upstream and API key authentication method. It does not send official login credentials to the relay or inject official state.

If CCS actually switches the provider, upstream, or authentication method, the service stops forwarding to avoid sending credentials to the wrong destination. The recommended switching order is:

1. Stop ccodex-sleep-state.
2. Switch the configuration in CCS.
3. Restart ccodex-sleep-state.
4. Restart Codex and create a new session.

If a configuration conflict occurs, do not delete transaction files or blindly edit the TOML manually. Open “Check and Repair Configuration,” preview the changes, prioritize retaining the current CCS configuration, and then take over again.

Stop the Service and Restore Configuration

Keep the terminal window open while the service is running. When you need to exit, press Ctrl+C in the terminal, wait for configuration restoration to complete, and then restart Codex.

Closing the browser, disabling state injection, and stopping the service are three different operations: closing the browser does not stop the background service; disabling injection may still allow requests to be forwarded; only ending the service process starts the stopping and configuration restoration flow.

Common Troubleshooting

The Panel Shows “Not Connected”

Starting the service does not mean Codex has completed the connection. Follow the configuration prompts in the panel and confirm that you are not using the read-only --no-config mode.

Codex Responds, but the Panel Shows No Requests

First restart Codex and create a new session. If there are still no records, check whether Codex is using another configuration, profile, project, or task-level override, or whether another instance is running at the same time.

codex_config_changed or 409 Appears

Open “Check and Repair Configuration,” preview the differences, prioritize retaining the current CCS configuration, and then take over again.

state_unavailable or Local 503 Appears

Check the account rule, collection diagnostics, and cooldown period. If you need to restore use first, explicitly select normal forwarding fallback or temporarily disable injection.

state_shape_changed Appears

This means the state format does not match the current rule. The official request may already have consumed quota, and the service will not replay it automatically. Check the account rule, upstream, and recent changes rather than simply modifying the length rule.

415 Appears

The new version supports gzip and zstd request encoding used by the official client. Confirm that an older version is not running, then inspect the sanitized diagnostics.

502, 503, or Timeout Appears

Check the proxy exit and upstream service status. Network failures cannot be fixed by modifying the state length.

401, 403, or 429 Appears

Check the login status, access permissions, or wait for rate limiting to recover, respectively. The project does not bypass these stop conditions by continually switching IPs.

Configuration File Is Corrupted

If the service JSON is corrupted, setup opens a read-only repair panel. Confirm the backup before rebuilding and restarting. If the Codex TOML is corrupted, retain the backup first, then use an explicit rebuild process or have CCS regenerate it. Do not try to infer the API key from the corrupted file.

Use doctor to Collect Diagnostics

Before providing troubleshooting information to maintainers, community members, or an AI Agent, Windows users can run:

.\ccodex-sleep-state.exe doctor

macOS users should run:

./ccodex-sleep-state doctor

When reporting an issue, it is usually sufficient to provide the operating system, Codex version, tool version, error message, and necessary redacted diagnostics. Do not send auth.json, administrative passwords, complete subscription links, account credentials, or the entire data directory.

Advanced Usage Tips

Confirm the Actual Configuration Directory

If CODEX_HOME is set, the tool follows that location. It also supports CCODEX_STATE_HOME and --data-dir. When you are unsure which configuration is currently in use, run:

ccodex-sleep-state paths

Do not guess the current configuration location based only on the directory name.

Understand Collection Costs and Cooldowns

State collection uses real quota. By default, each round attempts at most 6 candidate exits, each probe takes at most 20 seconds, and at least 180 seconds must elapse between collection rounds. Normal generation requests are not automatically replayed, so do not treat collection or exit switching as cost-free retries.

Isolate by Model and Account

Do not reuse state between Astra, Sol, and Terra. After changing the default model, restart Codex or create a new session. Whether a model can actually be called still depends on account permissions and whether the upstream provides that model.

Assess Compression Support Carefully

Project records show that real Sol's newer V2 remote compression and continuing to reply after compression have succeeded; the older V1 direct connection to the upstream returned 404. Before sending, bridging only completed testing with a local simulated client. An additional real acceptance test also encountered exit transmission failures, so not all compression methods can be considered fully working.

Important Limitations and Security Boundaries

• The currently supported models include only gpt-6-astra, gpt-5.6-sol, and gpt-5.6-terra.
• It currently uses Responses HTTP and SSE, does not support WebSocket, and does not provide arbitrary protocol conversion.
• The tool will not enable model permissions for an account or silently replace a model.
• It does not switch the system proxy, refresh Codex login, or use reset cards.
• The relay service being able to connect does not mean the turn-state approach will work with that relay.
• Authentication values and complete state are not written to regular logs. The project has no telemetry and does not upload logs to the author.
• Local proxy configuration and recovery backups may still contain sensitive information and must be stored securely.

Developer Information

The project is written in Go, and the static management page is embedded in the binary, so no separate frontend service is required. The main code structure includes:

• cmd/ccodex-sleep-state: commands, one-click entry points, and diagnostics.
• internal/codexconfig: provider parsing, configuration takeover, semantic checks, and recoverable fixes.
• internal/gateway: model and account isolation, collection, compression, and streaming forwarding.
• internal/turnstate: state wrapping rules, current values, and fallback values.
• internal/proxyroute: subscription parsing and outbound connections.
• internal/service: single-instance operation, web panel, hot configuration switching, and request diagnostics.

The project is licensed under GPL-3.0 and reuses Mihomo for its proxy component. This project is not affiliated with OpenAI, Mihomo, or GPT-Load.

Summary

The core value of ccodex-sleep-state is not a promise to remove rate limits or restore model quality, but to make Codex access, proxy exits, turn-state, configuration backups, and error diagnostics visible, inspectable, and recoverable. When using it for the first time, verify that the original Codex works first, then run setup, confirm the takeover through the panel, restart Codex, and create a new session. When problems occur, check the panel diagnostics first and run doctor; do not modify configuration blindly or expose sensitive credentials.