メインコンテンツへ移動
AIチュートリアル

ccodex-sleep-state チュートリアル：Codexを可視化して制御し、プロキシを設定して接続問題を解決する

このチュートリアルでは、WindowsとmacOSにccodex-sleep-stateをインストールし、Codexに接続する方法、プロキシとturn-stateポリシーの設定方法、ローカルパネルと診断コマンドを使ってレート制限、設定の競合、接続障害を調査する方法を紹介します。

約21分で読了
ccodex-sleep-state チュートリアル：Codexの制御、プロキシ設定、接続問題の解決

プロジェクト概要

ccodex-sleep-state は Go で開発されたローカルツールです。Codex の使用中に発生する可能性がある回答品質の変化、レート制限、接続失敗、設定の競合を改善することを目的としています。接続管理、プロキシ出口、turn-state の収集、設定の引き継ぎ、障害診断を1つのローカルサービスとWebパネルに集約し、設定ファイルを手動で変更する必要性を減らします。

最初に明確にしておく必要があります。このツールはアカウントの利用枠を増やすものではなく、出口を変更した後にモデル品質が必ず回復することを保証するものでもありません。接続、設定、レスポンス内の X-Codex-Turn-State を扱い、収集結果、注入状態、リクエスト経路、エラー原因を確認しやすくするものです。

プロジェクトは現在も公開ベータ版です。Release によって機能が異なる場合があるため、ダウンロードしたバージョンのリリースノートを基準にしてください。一部のモデルや圧縮フローでテストに成功したことを、すべてのシナリオで検証済みと解釈しないでください。

ccodex-sleep-state プロジェクト関連画面

主な機能

  • ローカルWebパネル：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 がない場合に注入を停止しますが、選択した出口を使って正式なリクエストを転送します。正式なリクエストの転送は最大1回で、注入されなかったことを明確に示し、収集成功を装うことはありません。

このモードはレート制限を解除するものではありません。401、403、429 が発生した場合も、サービスは停止ルールに従います。上流へ送信済みの正式な生成リクエストが、出口を変更した後に自動再実行されることはありません。

プロキシとサブスクリプションを設定する

すでにプロキシソフトウェアをインストールしている場合は、「サブスクリプションとプロキシ」ページでローカル HTTP、HTTPS、SOCKS5 アドレスを入力できます。初回の自動接続では、127.0.0.1 上の一般的な SOCKS5 ポートのみを確認します。LAN をスキャンしたり、プロキシソフトウェアのアカウントデータベースを読み取ったりすることはありません。

プロジェクトは 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 個の候補出口を試行し、1 回の探査は最大 20 秒、2 回の収集の間隔は少なくとも 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：単一インスタンス、Web パネル、設定のホットスイッチ、リクエスト診断。

このプロジェクトは GPL-3.0 ライセンスを採用しており、プロキシ部分では Mihomo を再利用しています。このプロジェクトは OpenAI、Mihomo、GPT-Load のいずれとも所属関係はありません。

まとめ

ccodex-sleep-state の核心的な価値は、レート制限の解除やモデル品質の回復を約束することではなく、Codex の接続、プロキシ出口、turn-state、設定バックアップ、エラー診断を可視化し、検査可能かつ復元可能にすることです。初めて使用する際は、まず元の Codex が利用可能であることを確認し、その後 setup を実行して、パネルで引き継ぎを確認し、Codex を再起動して新しいセッションを作成することを推奨します。問題が発生した場合は、まずパネルの診断を確認して doctor を実行し、設定をむやみに変更したり、機密性の高い認証情報を漏らしたりしないでください。