使用便携式安装套件构建执行优先的 Codex CLI 工作区

Codex CLI Portable Setup Kit 的作用

Codex CLI Portable Setup Kit 是由社区维护的 OpenAI Codex CLI 配置和安装程序。它并非 Codex 本身，也不是 OpenAI 官方产品。

该套件改变了 Codex 处理代码仓库任务的方式。其指令强调检查工作区、使用可用工具、进行所需修改、运行检查、诊断故障并报告经过验证的结果。便携性只是交付机制；其核心产品是这种执行优先的工作方式。

重要提示：TURBO 模式会启用高权限、非交互式行为，包括 approval_policy = "never"。请仅在你信任的工作区中使用，并事先审查该软件包。标准公开配置默认采用更安全的按请求审批和工作区写入沙箱。

主要功能

• 执行优先指令：Codex 会直接处理实际目标，而不是仅提供通用建议或计划便停止。
• 一键启动 TURBO：TURBO.cmd 会验证工作区、配置高权限执行策略、继承原生模型设置并启动 Codex。
• 事务式安装：安装程序会验证 SHA-256 清单、创建带时间戳的备份、记录操作日志并生成回滚回执。
• 确定性分析工具：纯 Python 的 re-toolkit 可处理 PE32 和 PE32+ 检查、x86 和 x64 反汇编、AOB 扫描、微型仿真、Protobuf 和 TLV 分析、Frida Hook 生成以及二进制差异分析。
• 双阶段处理：将结构规划与高保真渲染分离，以减少占位符伪影和长篇输出质量下降。
• 多种智能体格式：该软件包为 Codex CLI、OpenCode、Claude Code、Cursor、Windsurf 和 ChatGPT App 提供指令或预设。
• 连续性支持：Hook 和上下文工具有助于在较长任务中保留已验证状态。
• 可逆的 Git 集成：安装程序可将 core.hooksPath 绑定到软件包提供的预提交防护，并在回滚时恢复原值。

要求与准备工作

该代码仓库将 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 Hook 路径。
7. 按要求尝试设置可选插件，但不会将插件安装失败视为致命错误。
8. 写入 receipt.json 和 last-receipt.txt。

每次替换都会在执行前记录。如果后续安装步骤失败，安装程序会以相反顺序重放操作列表，并恢复先前的 Git Hook 绑定。

安装程序添加的内容

• Codex 用户配置：%CODEX_HOME% 或 ~/.codex 下的文件，包括 config.toml、AGENTS.md、指令、初始规则和技能。
• 用户级智能体技能：~/.agents 下的可复用技能。
• 项目配置：AGENTS.md、CLAUDE.md、.codex、.agents、.gitignore、上下文工作流、Hook 和逆向工程工具包。
• 本地 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'

验证是该设计的重要组成部分。安装程序会在写入前检查清单，并阻止通过清单进行路径遍历。该代码仓库还介绍了用于发布测试的九步 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

此命令会在无 Schema 的情况下检查 Protobuf 线格式数据。该子系统还包括 TLV 帧解析功能。

仿真一小段指令序列

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

微型仿真器为受支持的 CPU 级分析提供隔离的寄存器、堆栈和内存沙箱。

生成 Frida Hook

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

此命令会将原始二进制文件与修改后的副本进行比较，并输出补丁信息。

以十六进制转储形式检查区域

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

此命令会将从偏移量 0x100 开始的 128 字节格式化为对齐的十六进制转储。

运行双阶段流水线

该项目包含一个将结构规划与最终渲染分离的双阶段流水线。第一阶段创建结构和主要情节点，第二阶段生成完整输出。这种分离方式旨在减少注意力崩溃、内容截断，以及 ROLE_A 和 ROLE_B 等字面占位符伪影。

python .agents/tools/re-toolkit/cli.py pipeline "你的复杂场景或系统架构提示词"

此工作流最适合在详细生成前受益于明确结构准备的复杂提示词。

配置其他受支持的智能体工具

该软件包为多个智能体环境提供原生配置文件，包括 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 "对目标模块进行逆向工程并提取内存偏移量" --target game.dll --json

请仅对你获授权检查的软件和数据使用二进制分析功能。

保留回执

如果可能需要撤销安装，请勿删除生成的回执。回执保存了删除新安装文件、恢复被替换文件以及还原先前 Git Hook 配置所需的操作顺序。

了解标准安全默认值

除非明确选择 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、规则、Hook、技能和插件的官方文档。

总结

Codex CLI Portable Setup Kit 将以执行为中心的 Codex 配置文件、项目指令、智能体集成、确定性分析工具、验证、备份和回滚功能整合到一套可复现的安装方案中。如果你需要可审查的控制机制，请先采用标准事务式安装并验证结果；只有在可信工作区适合使用高权限、非交互式行为时，才启用 TURBO 模式。