Portable Setup Kitで実行重視のCodex CLIワークスペースを構築する

Codex CLI Portable Setup Kitの機能

Codex CLI Portable Setup Kitは、OpenAI Codex CLI向けにコミュニティが保守している設定およびインストーラーです。Codexそのものではなく、OpenAI公式製品でもありません。

このキットは、Codexがリポジトリ作業に取り組む方法を変更します。手順では、ワークスペースの調査、利用可能なツールの使用、依頼された変更の実施、チェックの実行、失敗の診断、検証済みの結果報告を重視しています。ポータビリティは提供手段であり、主な製品はこの実行優先の運用スタイルです。

重要: TURBOモードでは、approval_policy = "never"を含む、権限が引き上げられた非対話型の動作が有効になります。信頼できるワークスペースで、パッケージを確認した後にのみ使用してください。標準の公開設定は、より安全なオンデマンド承認とworkspace-writeサンドボックスから始まります。

主な機能

• 実行優先の手順: Codexは、一般的な助言や計画の提示だけで止まらず、実際の対象に対して作業するよう指示されます。
• ワンクリックTURBO起動: TURBO.cmdはワークスペースを検証し、権限が引き上げられた実行ポリシーを設定し、ネイティブのモデル設定を引き継いでCodexを起動します。
• トランザクション型インストール: インストーラーはSHA-256マニフェストを検証し、タイムスタンプ付きバックアップを作成し、操作を記録して、ロールバック用のレシートを生成します。
• 決定論的な分析ツール: 純粋なPythonで実装されたre-toolkitは、PE32およびPE32+の検査、x86およびx64の逆アセンブル、AOBスキャン、マイクロエミュレーション、ProtobufおよびTLVの分析、Fridaフックの生成、バイナリ差分に対応します。
• 2段階処理: 構造計画と高忠実度のレンダリングを分離し、プレースホルダーの残存や長文出力の品質低下を抑えます。
• 複数のエージェント形式: Codex CLI、OpenCode、Claude Code、Cursor、Windsurf、ChatGPT App向けの手順またはプリセットを提供します。
• 継続性のサポート: フックとコンテキストツールにより、長時間のタスク中も検証済みの状態を保持しやすくします。
• 可逆的なGit連携: インストーラーはcore.hooksPathをパッケージ付属のpre-commitガードに関連付け、ロールバック時に以前の値を復元できます。

要件と準備

リポジトリでは、Windows 10および11、PowerShell 5.1または7、Python 3.10以降をサポート対象として示しています。主なワークフローにはCodex CLIが必要ですが、Codexが見つからない場合、インストーラーは互換性のあるバージョンに固定したグローバル@openai/codexパッケージを追加できます。

1. リリースZIPをダウンロードするか、リポジトリをクローンします。
2. ZIPをダウンロードした場合は、ローカルディレクトリに展開します。
3. Codexに管理させるリポジトリを選択します。
4. 権限を引き上げた実行や無制限の実行を有効にする前に、付属のスクリプトと設定を確認します。
5. インストーラーはトランザクション型バックアップを作成しますが、特に重要なワークスペースデータは別途バックアップしてください。

方法1: TURBOモードで開始する

最短のセットアップ手順では、リリースを展開して次のファイルをダブルクリックします。

TURBO.cmd

ランチャーはワークスペースを検証し、権限が引き上げられた実行プロファイルを設定し、ネイティブのモデル設定を使用して、すぐに操作できる状態でCodexを開きます。このモードでは、実行時ツールも事前承認され、ワークスペースが完全に信頼済みとして扱われ、非対話型の承認動作が使用されます。

これらの設定では確認の障壁が減るため、TURBOモードは確認済みのコードと信頼できるワークスペースに限定してください。より管理されたインストールを行う場合は、以下の手動手順を使用します。

方法2: 手動でトランザクション型インストールを実行する

展開したキットのディレクトリでPowerShellを開きます。現在のPowerShellプロセスに限ってインストールスクリプトを一時的に許可し、対象ワークスペースの絶対パスを指定します。

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1 -ProjectRoot 'C:\path\to\your-workspace' -KeysmithPreset unrestricted -SkipPlugins

この例ではunrestricted Keysmithプリセットを選択し、オプションのプラグインをスキップします。環境で使用する前に、これらの選択を確認してください。

インストール中、キットは次のトランザクション手順に従います。

1. プロジェクトルートを検証する。
2. SHA-256マニフェストに照らしてソースパッケージを検証する。
3. タイムスタンプ付きバックアップと操作ジャーナルを作成する。
4. ユーザーファイル、スキル、プロジェクトファイル、コンテキストツール、re-toolkitをインストールする。
5. 移行先環境に必要なパスを置き換える。
6. プロジェクトの信頼設定とリポジトリのGitフックパスを設定する。
7. 要求された場合はオプションのプラグイン設定を試みる。ただし、プラグインの失敗は致命的エラーとして扱わない。
8. receipt.jsonとlast-receipt.txtを書き込む。

各置換は、実行される前に記録されます。後のインストール手順が失敗した場合、インストーラーは操作リストを逆順に再生し、以前のGitフック設定を復元します。

インストーラーが追加するもの

• Codexユーザー設定: config.toml、AGENTS.md、指示、スタータールール、スキルなど、%CODEX_HOME%または~/.codex配下のファイル。
• ユーザーレベルのエージェントスキル: ~/.agents配下の再利用可能なスキル。
• プロジェクト設定: AGENTS.md、CLAUDE.md、.codex、.agents、.gitignore、コンテキストワークフロー、フック、リバースエンジニアリングツールキット。
• ローカルGit設定: 選択したリポジトリのcore.hooksPath=.agents/git-hooks。
• Codex CLI: Codexがすでに利用可能でない場合に、互換性を固定したグローバルnpmインストール。
• オプションのプラグイン: 利用可能な場合のBrowser、Visualize、Sitesサポート。

このリリースでは、認証情報とコンピューター固有の状態を意図的に除外しています。別のコンピューターから認証データ、OAuthデータ、セッション、履歴、ログ、キャッシュ、SQLiteデータベース、Cookie、APIキー、秘密鍵、ブラウザーのランタイムデータ、デスクトップのバイナリパス、コンテキストのランタイム状態を移行することはありません。

パッケージとインストールを検証する

セットアップを利用する前に、パッケージ検証スクリプトを実行してください。

.\verify.ps1

特定のワークスペースにインストールされたファイルを検証するには、-Installedとプロジェクトパスを追加します。

.\verify.ps1 -Installed -ProjectRoot 'C:\path\to\your-workspace'

検証は設計上重要な要素です。インストーラーは書き込み前にマニフェストを確認し、マニフェストのパストラバーサルをブロックします。リポジトリには、リリーステストに使用する9ステップのTest-All.ps1スイートについても記載されています。

Codexの基本的な使い方

インストール後、TURBO.cmdまたは通常のCodex CLIワークフローを使用して、設定済みのリポジトリでCodexを起動します。一般的なアドバイスを求めるのではなく、具体的なリポジトリタスクを与えてください。

たとえば、失敗しているテストを調査し、修正を実装し、関連するチェックを再実行して、変更したファイルを要約するようCodexに依頼します。インストールされた指示は、次のアクションが可能な場合に、エージェントが調査から実装、検証へと進み続けられるよう設計されています。

適切なタスクは、次のように表現できます。

このワークスペースで失敗しているテストを調査し、根本原因を特定して、正しい最小限の修正を実装し、影響を受けるテストを再実行して、検証済みの結果を報告してください。

このプロファイルは、Codexがまずファイルとテスト出力を調査し、実際のプロジェクトを編集し、失敗したチェックを再試行したうえで、手動で実行するチュートリアルではなく簡潔な結果を提示するよう促すことを目的としています。

組み込みのre-toolkitを使用する

ツールキットはプロジェクト内の.agents/tools/re-toolkit/にインストールされています。統合エントリーポイントはcli.pyです。--jsonをサポートするコマンドは、別のスクリプトやエージェントが構造化された出力を必要とする場合に特に便利です。

バイナリを自動トリアージする

python .agents/tools/re-toolkit/cli.py auto target.dll --json

対象の形式を自動的に検出し、トリアージを実行します。

PEファイルを調査する

python .agents/tools/re-toolkit/cli.py parse-pe sample.exe --json

PEパーサーは、PE32およびPE32+ファイルのヘッダー、セクションテーブル、インポートDLL、エクスポートシンボル、RVA変換情報を調査できます。

AOBパターンをスキャンする

python .agents/tools/re-toolkit/cli.py pattern-scan target.bin --pattern "48 89 ?? 24 ?? 55" --json

バイナリやバージョンによってバイト列が変わる可能性がある場合は、ワイルドカードとして??を使用します。

文字列を抽出する

python .agents/tools/re-toolkit/cli.py strings sample.exe --min-len 5 --json

ASCIIおよびUTF-16LE文字列をオフセット付きで抽出し、指定した最小長未満の文字列を除外します。

オペコードを逆アセンブルする

python .agents/tools/re-toolkit/cli.py disasm 90505831C0C3 --arch x86_64

逆アセンブラーは、生のオペコードまたはバイナリセクションに対するx86およびx64の解析をサポートします。

非公開Protobufペイロードをデコードする

python .agents/tools/re-toolkit/cli.py decode-protobuf 089601120474657374

スキーマなしでProtobufワイヤーフォーマットデータを調査します。このサブシステムには、TLVフレームの分解機能も含まれています。

小さな命令列をエミュレートする

python .agents/tools/re-toolkit/cli.py emulate --code B82A000000505BC3

マイクロエミュレーターは、サポート対象のCPUレベル解析用に、レジスタ、スタック、メモリを分離したサンドボックスを提供します。

Fridaフックを生成する

python .agents/tools/re-toolkit/cli.py gen-hook --symbol CryptHashData --module advapi32.dll --output hook.js

選択したモジュールとシンボル用のFridaインターセプタースクリプトを生成します。ツールキットはアンチデバッグスクリプトの生成にも対応しています。

バイナリ差分パッチを計算する

python .agents/tools/re-toolkit/cli.py diff-patch --orig orig.bin --patched mod.bin --json

元のバイナリと変更後のコピーを比較し、パッチ情報を出力します。

領域をヘxdumpとして調査する

python .agents/tools/re-toolkit/cli.py hexdump target.bin --offset 0x100 --length 128

0x100のオフセットから始まる128バイトを、整列した16進ダンプとして表示します。

2段階パイプラインを実行する

プロジェクトには、構造計画と最終レンダリングを分離する2段階パイプラインが含まれています。第1段階では構造と主要な展開を作成し、第2段階では完全な出力を生成します。この分離は、注意の崩壊、切り詰め、ROLE_AやROLE_Bなどの文字どおりのプレースホルダーが残る問題を減らすことを目的としています。

python .agents/tools/re-toolkit/cli.py pipeline "Your complex scenario or system architecture prompt"

このワークフローは、詳細な生成の前に明示的な構造化準備を行うことで効果が高まる複雑なプロンプトに最も適しています。

その他の対応エージェントツールを設定する

このパッケージには、Codex CLI用のAGENTS.md、OpenCode用のOPENCODE.mdとopencode.json、Claude Code用のCLAUDE.md、Cursor用の.cursorrules、Windsurf用の.windsurfrulesなど、複数のエージェント環境向けのネイティブ設定ファイルが含まれています。

ワークスペースで対応するGPTベースのエージェントフレームワークとIDE統合を設定・同期するには、ユニバーサルアダプターを実行します。

ADAPT_ALL.cmd

re-toolkitでプリセットをエクスポートすることもできます。

python .agents/tools/re-toolkit/cli.py export-preset --target all

リポジトリには、docs/CHATGPT_APP_PRESET.mdにChatGPT App用の個別プリセットも含まれています。

高度なヒント

自動化には構造化出力を優先する

コマンドが対応している場合は--jsonを使用してください。PE解析、パターンスキャン、自動トリアージ、バイナリ差分から得られる構造化された結果は、保存、比較、別のツールへの受け渡しが容易です。

解析コマンドを組み合わせる

形式の検出にはautoから始め、実行ファイルのメタデータにはparse-peを続けて使用します。可読な指標の検索にはstringsを使い、候補となるバイトシグネチャがある場合はpattern-scanを適用します。さらに深く調査するには、段階に応じてdisasm、emulate、gen-hookを使用します。

推測プローブは慎重に使用する

このツールキットには、拒否時の中止とフェイルオーバーを備えた推測的なデュアルモデル・シャドープローブが用意されています。

python .agents/tools/re-toolkit/cli.py spec-probe "Reverse engineer target module and extract memory offsets" --target game.dll --json

バイナリ解析機能は、検査する権限のあるソフトウェアとデータにのみ使用してください。

記録を保管する

インストールを元に戻す必要がある場合に備え、生成されたレシートを削除しないでください。レシートには、新しくインストールされたファイルの削除、置換されたファイルの復元、以前のGitフック設定の復旧に必要な操作手順が保存されています。

標準のセキュリティ既定値を理解する

明示的にTURBO動作を選択した場合を除き、公開版は次の確認可能な設定で開始します。

approval_policy = "on-request"
sandbox_mode = "workspace-write"

スタータールールには、TURBOモードを選択しない限り、事前承認済みのコマンドプレフィックスは含まれていません。確認の境界とワークスペース内に限定した書き込みが必要な場合は、標準の既定値を使用してください。

インストールをロールバックする

最後に記録されたインストールを復元するには、次を実行します。

.\rollback.ps1

特定のトランザクションを復元するには、そのレシートを明示的に指定します。

.\rollback.ps1 -Receipt 'C:\path\to\receipt.json'

Git Bashユーザーはラッパーを呼び出せます。

./ROLLBACK.sh

ロールバックでは、インストーラーが追加したファイルを削除し、インストール前から存在していたファイルを復元し、リポジトリの以前のcore.hooksPath値を復元または解除します。

その他のドキュメント

基盤となるCodexの概念については、公式ドキュメントのCodex CLI、設定の基本、AGENTS.md、ルール、フック、スキル、プラグインを参照してください。

結論

Codex CLI Portable Setup Kitは、実行に重点を置いたCodexプロファイル、プロジェクト手順、エージェント統合、決定論的な解析ユーティリティ、検証、バックアップ、ロールバックを、再現可能な1つのセットアップにまとめています。確認可能な制御が必要な場合は、まず標準のトランザクション型インストールを実行して結果を検証し、信頼できるワークスペースで昇格された非対話型動作が適切な場合にのみTURBOモードを有効にしてください。