OpenAI 刚开源的 Codex Security，现在可以在本地电脑跑起第一轮扫描。GitHub 上的 openai/codex-security 采用 Apache-2.0 协议发布，开源部分是负责发起扫描、管理结果和接入 CI 的工具层；真正读取代码、在隔离环境里重现漏洞并生成修补文件的分析服务，仍部署在 OpenAI 自有服务器上。
这也意味着，把源码 clone 到本地，不等于马上就能完整使用。根据 README 的环境要求，用户仍需登录 OpenAI 账号，并具备 Codex Security 的访问权限。目前该产品处于研究预览阶段，面向 ChatGPT Pro、Business、Edu 和 Enterprise 用户开放，企业账号还可能需要管理员先开启权限。
开源的是工具外壳，不是全部分析能力
原文指出，这次放出的代码主要覆盖“跑扫描、管结果、接 CI”这一层。真正执行分析的后端服务并未开源，因此扫描流程仍依赖 OpenAI 的账号体系和权限控制。
版本更新节奏也很快。npm 上的 @openai/codex-security 首个版本 0.1.0 于 7 月 28 日世界标准时间 17:09 发布，0.1.1 又在同一天 23:48 上线，两次发布时间相隔 6 小时 39 分。SDK 文档同时写明，在 1.0.0 之前，公开 API 可能会在 minor 版本之间发生变化，准备接入生产环境的团队更适合锁定版本。
仓库开源，但不接受外部 PR 直接并入
根据 CONTRIBUTING.md，这个仓库是从 OpenAI 内部 canonical repository 单向镜像出来的。外部开发者可以提 issue、报告 bug，也可以提出功能需求，但外部 pull request 无法直接并入原始代码库。
这意味着，授权层面仍允许用户修改和再分发代码，协作方式则由 OpenAI 维护团队控制，两者并不是一回事。
环境要求与首次安装流程
要运行 Codex Security，环境要求包括三项：
- Node.js 22 以上，因为该包是 ESM-only，旧版本无法运行；
- Python 3.10 以上，扫描和导出流程都会用到；
- 拥有 Codex Security 的访问权限。
官方说明显示，macOS、Linux 和 Windows 都支持。安装与首次登录可以用以下三行命令完成：
npm install @openai/codex-securitynpx codex-security loginnpx codex-security scan .
如果运行环境在远程主机，或者没有浏览器，可以改用设备认证：
npx codex-security login --device-auth
CI 环境则不需要交互式登录，只需设置环境变量：
export OPENAI_API_KEY=<YOUR_KEY>
想确认当前生效的是哪一组凭证，可以运行：
npx codex-security login status
该命令会显示凭证来源，但不会直接打印密钥内容。
正式扫描前，建议先空跑一次
在直接执行 scan . 之前，原文建议先做一次 dry run：
npx codex-security scan . --dry-run
这一步不会启动 Codex，不会访问网络，也不会加载凭证。它只会验证仓库、扫描目标、输出路径和模型配置，并提示本次扫描将使用哪个模型、采用什么推理强度。因为这一步不产生费用，适合在正式扫描前先检查配置。
默认模型与推理强度会影响成本
Codex Security 默认使用 gpt-5.6-sol，推理强度为 extra-high。如果要切换模型，可以使用：
npx codex-security scan . --model gpt-5.6-terra
也可以通过 --codex KEY=VALUE 覆盖其他设置，例如把推理强度调低一级：
npx codex-security scan . --codex 'model_reasoning_effort="high"'
原文提醒，推理强度会直接影响 token 消耗，也就直接关系到账单。首次尝试时，没有必要默认使用最高强度。
5 个容易花冤枉钱或白做工的常见坑
1. --max-cost 不是硬性封顶
虽然 --max-cost 看上去像成本保险，但官方说明明确写道：当累计成本超过上限时，扫描会停止，包括已派出的 worker；不过，已经执行中的 request 仍可能在超出上限后完成。
也就是说，若把上限设为 5 美元，实际账单仍可能高于 5 美元。第一次扫描更适合先选规模较小的仓库，或者通过 --path 限定范围：
npx codex-security scan . --path src --max-cost 5
每次扫描给出的估算成本，按照 OpenAI 标准 API token 价格计算，包含缓存输入和缓存写入，但不包含手续费和附加费，因此只能视为下限。
2. 输出目录放在仓库里会被直接拦下
扫描结果输出目录必须位于被扫描目录之外，而且还要位于任何包裹它的 Git worktree 之外。如果把输出目录放进 repo 内部，CLI 会直接拒绝执行。
原因在于，扫描结果可能包含源代码片段、漏洞细节和重现步骤，等同于一份攻击路径说明。若被误提交到仓库，风险会被放大。
在 macOS 和 Linux 上，若输出目录已经存在，还必须满足 chmod 700 权限要求，只允许当前用户读写，否则同样会被拦下。示例如下：
mkdir -p ~/security-scans/myrepochmod 700 ~/security-scans/myreponpx codex-security scan . --output-dir ~/security-scans/myrepo
如果目录中已有旧结果，可以加上 --archive-existing，CLI 会先把旧内容搬到 <output-dir>.previous-<timestamp>-<id>，然后在原路径创建新的干净目录。配合 --dry-run 使用时，还能先查看将要移动到哪里，而不会真的改动文件。
3. 环境变量中的 API 密钥会覆盖 ChatGPT 登录
默认优先级是环境变量中的 API 密钥高于本地保存的 ChatGPT 登录状态。交互式扫描时，工具会询问使用哪一组凭证；但在 JSON 输出、空跑和 CI 这类非交互场景中，不会出现选择提示，而是直接采用 API 密钥优先规则。
结果可能是，用户以为自己在消耗 ChatGPT 方案额度，实际却记账到 API 侧。若要强制指定凭证类型，可以这样写：
npx codex-security scan . --auth chatgptnpx codex-security scan . --auth api-key
其中，--auth chatgpt 会完全忽略 OPENAI_API_KEY 和 CODEX_API_KEY。如果希望长期默认走 ChatGPT 登录，则需要清除这两个环境变量：
unset OPENAI_API_KEY CODEX_API_KEY
4. Python 3.10 需要额外安装 tomli
虽然官方写明支持 Python 3.10 以上，但若当前环境正好是 3.10，还需要手动安装 tomli。从 3.11 开始，标准库已内置 tomllib，不再需要单独补装。
如果要切换解释器，也可以通过 --python 参数、SDK 中的 pythonPath 或 PYTHON 环境变量指定。
5. MCP 只提供只读信息，不能发起扫描
CLI 支持通过 npx codex-security mcp add 注册成 MCP（Model Context Protocol，模型上下文协议）服务器，但 MCP 侧仅开放只读的 metadata 查询。
扫描、批量扫描、认证、导出、验证和修补，都必须通过 CLI 完成。官方给出的理由是，MCP 传输层无法取消执行中的扫描；如果一个任务停不下来却持续计费，问题会更大。
如何接入 commit 前检查和 CI
在本地开发环节，可以先安装 commit 前检查 hook：
npx codex-security install-hook
安装后，每次 commit 前都会扫描已暂存和未暂存的改动。它会遵守 core.hooksPath 设置，也不会覆盖已有 hook。默认情况下，发现 high 及以上级别问题时会阻断提交，阈值可以通过 --fail-on-severity 调整。
在 CI 中，原文给出了一套标准写法：
SCAN_ROOT="$(mktemp -d)"npx codex-security scan . \ --diff origin/main \ --output-dir "$SCAN_ROOT/results" \ --json \ --fail-on-severity high > "$SCAN_ROOT/findings.json"
--diff origin/main 只扫描当前变更涉及的部分，成本通常低于整库扫描；而 --working-tree 用于扫描已暂存和未暂存改动。
工具的退出码也有明确设计：
- 0：report-only 扫描完成，或策略校验通过；
- 1：扫描完成，但违反策略；
- 2：输入无效、覆盖不完整，或运行时与导出错误；
- 130：被中断；
- 143：被终止。
其中，“覆盖不完整”被归到 2，而不是 0，目的就是避免扫描中途失败却被误判为通过。即使扫描没有完整结束，可用结果仍会写入 stdout，覆盖率警告则写到 stderr；report-only 模式同样如此。进度消息走 stderr，结构化结果走 stdout，因此在使用 --json 重定向到文件时，不会被进度输出污染。
导出 SARIF、CSV、JSON 不会再次计费
如果要把扫描结果接入现有安全平台，可以使用 export 命令：
npx codex-security export ~/security-scans/myrepo \ --export-format sarif \ --output ~/security-scans/results.sarif
目前支持 SARIF、CSV、JSON 三种格式。生成 SARIF 时，工具还会同时向 <scan-dir>/exports/results.sarif 写入一份结果；如果加上 --source-root，还可以补充源码行的识别指纹。
原文特别强调，export 不会启动 Codex，也不会加载凭证，因此不会产生新的费用。换句话说，扫描完成后若只想转换输出格式，直接导出即可，不需要重新扫描。
扫描历史、误报标记与二次比对
扫描记录默认保存在本地 SQLite 数据库，路径为 $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3。如果该位置不可写，可以通过 CODEX_SECURITY_STATE_DIR 改到其他目录。
与扫描历史相关的常用命令包括：
npx codex-security scans listnpx codex-security scans show SCAN_IDnpx codex-security scans rerun SCAN_ID
其中 scan ID 不必输入完整串，只要至少提供 8 个字符 的前缀即可识别。
在漏洞修复后，如果想确认问题是否真正消失，可以使用 scans rerun，它会沿用原先配置，对当前 checkout 再执行一遍。若要比较两次扫描结果，可以使用：
npx codex-security scans match BEFORE_ID AFTER_IDnpx codex-security scans compare BEFORE_ID AFTER_ID
match 会将属于同一根本原因的发现串联起来，compare 则据此把结果分成 新增、持续存在、重新出现、已解决、未知 五类。
这里有一个细节：如果第二次扫描不完整，或者覆盖范围小于第一次，原本“消失”的发现不会被判定为“已解决”，避免因为扫描范围缩小而出现漏洞已修复的假象。
误报标记则可以通过以下命令处理：
npx codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
其中 --reason 不是形式字段。后续扫描只有在相同理由仍成立时，才会继续忽略该发现；如果代码发生变化，例如对应路由不再检查权限，该问题仍会重新出现。
支持批量扫描多个 GitHub 仓库
在完成 gh auth login 后，可以直接执行：
npx codex-security bulk-scan
该命令会抓取用户在过去 90 天 内有 push 记录的 GitHub 仓库，排除 archived 和 fork 项目，然后提供搜索、勾选和确认步骤。确认后的仓库列表会保存为 <output-dir>/repositories.csv，方便后续重跑或续跑。
也可以自行准备 CSV 清单。必要字段包括 id、repository、revision，其中 revision 必须填写完整 commit hash；可选字段 scope 和 mode 用于控制单个扫描范围。并发数由 --workers 控制，重试次数由 --max-attempts 指定。
仓库中还附带 Dockerfile 和 compose.yaml，容器配置默认关闭高风险能力，包括 cap_drop: ALL、no-new-privileges、自定义 seccomp profile，以及非 root 用户 10001。如果准备在共享机器上做批量扫描，这套配置可以直接作为基础模板。
附带 SDK、参考资源与常见问题
原文列出的延伸资源包括 openai/codex-security GitHub 仓库与 README、Codex Security CLI 官方快速上手、TypeScript SDK 官方指南、npm 套件页，以及结构化输出和代理探索框架 Incur。文中提到，CLI 中的 --llms、--schema 等参数即来自 Incur。
如果不想手动敲命令，也可以用 TypeScript SDK 调用。原文给出的最小示例如下：
import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
try { const result = await security.run("/path/to/repository", { outputDir: "/path/outside/repository/results", });
console.log(result.reportPath); console.log(result.findings.findings.length);} finally { await security.close();}
SDK 支持整库扫描、指定路径扫描、已提交 diff 扫描和工作树扫描四类目标；preflight() 对应 CLI 的 dry run；onWorkerStatus 和 onReconnect 可用于观察长时间扫描进度，也支持通过 AbortSignal 取消任务。
常见问题部分则进一步明确了几个边界：没有 ChatGPT Pro 或企业方案时，仅下载源码无法真正使用；单次扫描没有固定价目，只能按实际 token 用量估算；Windows 也支持运行，在 PowerShell 中可使用 $env:OPENAI_API_KEY = "<your-api-key>" 后再执行 npx codex-security scan C:\code\repository。
这篇教程由 Mickey帽鼠 整理撰写，参考资料为 openai/codex-security 官方 README 与 CLI 文档。