codex-security scan 报错的 6 个排查点

结论：临时排查、本机扫描和 CI 命令行接入，优先使用 Codex Security CLI；已有 TypeScript 项目需要内嵌扫描、获取报告路径时，再选择 TypeScript SDK。npx @openai/codex-security scan . 跑不起来时，先查运行时版本、认证方式和 Codex Security 访问权限，不要一上来就怀疑仓库代码。

GitHub 趋势中的 codex-security 对应 OpenAI 的安全扫描工具，npm 包名是 @openai/codex-security。它覆盖漏洞发现、验证、补丁生成和 PR 创建，但发布时仍处于早期阶段，参数和行为可能继续调整。

scan . 跑不起来时先查版本、认证和权限

先确认命令能运行，再看扫描结果。可以在项目中安装包，并通过当前版本的帮助信息确认命令和参数：

npm install @openai/codex-security
npx @openai/codex-security@latest --help

调用时统一使用带 scope 的包名 npx @openai/codex-security，不要把 npm 包名、旧命令别名和不同资料里的参数混在一起。旧文章出现过的参数如果不在当前 --help 中，就不应直接写进 CI 脚本。

1. 先确认命令调用的是正确的包。如果提示找不到命令，先确认安装的是 @openai/codex-security，再重新运行 npx @openai/codex-security@latest --help。不要因为文档里出现过 npx codex-security，就直接把它当成完全等价的包名。

2. 再核对 Node.js 和 Python 是否满足要求。现有资料对版本范围略有差异：一份列出 Node.js 22.13.0 或更高版本、24.x 和 26.x，另一份概括为 Node.js 22 以上和 Python 3.10 以上。保守做法是准备 Node.js 22.13.0 与 Python 3.10，发布前再核对仓库 README 中当前支持的版本线。

bash
node --version
npm --version
python3 --version

1. 本地交互登录和 CI 认证需要分别处理。本地交互式使用可以执行：

bash
npx @openai/codex-security login

CI 则不应等待交互登录，而应通过 CI Secret 注入 OPENAI_API_KEY 或 CODEX_API_KEY：

bash
export OPENAI_API_KEY="<your-key>"
# 或 export CODEX_API_KEY="<your-key>"

项目资料称，环境变量中的 API 密钥会直接传给当前扫描，不写入 Codex 凭据目录或系统密钥环；即便如此，也不要把密钥写进仓库、命令行参数或 CI 日志。

1. 检查账号是否拥有 Codex Security 权限。安装成功和认证成功并不等于账号已经获得扫描权限。资料还提到，部分网络安全请求需要在 chatgpt.com/cyber 申请“网络可信访问”审批。如果请求明确被权限或网络审批拦截，应先完成对应授权，再重试扫描。

2. 检查扫描状态目录是否可写。扫描历史会保存在 Codex Security 工作目录。如果默认目录不可写，可以将 CODEX_SECURITY_STATE_DIR 指向另一个可写位置：

bash
export CODEX_SECURITY_STATE_DIR="/path/to/writable/codex-security-state"

当前资料没有给出可直接硬编码的默认目录结构，因此排查时先检查目录权限和该环境变量，不要猜路径。

1. 没有代码差异、补丁或 PR 时，先确认是否只执行了普通扫描。scan . 本身不会修改仓库文件，只有显式加入 --patch 才会进入修改阶段。生成 PR 还需要 --create-pr，并确认目标发现没有被严重性阈值排除、补丁通过验证，以及当前账号具备提交分支和创建 GitHub Pull Request 的权限。

排除前五项后，在仓库根目录执行第一次扫描：

npx @openai/codex-security scan .

扫描结束后会显示发现结果摘要。交互式流程会询问是否打开发现结果浏览器，其中可以查看完整详情、设置严重性阈值、选择单个发现，并为选中的结果添加补丁指令。这些命令和检查本身都不会改动仓库代码。

项目资料称，该工具会结合代码语义和潜在攻击路径验证漏洞并过滤误报，但这不代表固定准确率，也不能替代人工复核。扫描结果更适合作为候选安全发现，而不是漏洞已经被证明的结论。

CLI 与 TypeScript SDK：选入口，也别混淆报告位置

CLI 和 TypeScript SDK 是同一类 Codex Security 能力的两个入口，不是两套彼此独立的安全结论来源。区别主要在调用方式：

如果团队只是临时检查一个仓库，或者要在 GitHub Actions、GitLab CI 等流水线里执行扫描，没有必要先引入 SDK。只有当现有 TypeScript 项目确实需要控制调用时机、归档报告路径或把扫描纳入内部任务系统时，SDK 才更合适。

当前资料没有提供可以核实的 SDK import、类名和方法签名，因此不应该凭印象写一段可能无法编译的示例代码。应以当前 SDK 文档为准，先确认调用入口、参数、返回对象和错误处理方式。

排查结果保存问题时，还要分清三件事。一次扫描结束后拿到的是扫描报告，SDK 的已知能力之一是取得这个报告路径；多次运行的跟踪信息属于扫描历史，资料称它保存在 Codex Security 工作目录；CODEX_SECURITY_STATE_DIR 则是默认状态目录不可写时的迁移入口。找到一份报告，并不代表历史记录丢失，反过来也一样。

CI 中需要机器可读输出时，可以使用：

npx @openai/codex-security scan . --json

现有资料没有列出 JSON 的具体字段，也没有给出发现漏洞时对应哪个退出码。因此，CI 解析器、失败判定和门禁规则都需要根据当前官方文档或实际行为自行验证，不能直接假设“输出里有 finding”就一定返回非零状态。

“接进 CI”也不等于“自动阻止合并”。退出码如何解释、哪些严重性需要阻断、是否保护主分支，仍需团队自行配置。在确认这些行为之前，更稳妥的做法是先保存 JSON 输出和报告路径，把扫描结果接入看板或告警，再逐步增加阻断规则。

--patch 之后的验证、PR 与边界

普通扫描不会修改仓库，只有 --patch 才会让工具进入补丁生成阶段。需要同时发现漏洞、生成补丁并输出机器可读结果时，可以组合使用：

npx @openai/codex-security scan . --patch --patch-severity high --json

这里 --patch-severity high 是补丁流程的严重性门槛。目标发现没有达到设定条件，就不会进入对应的补丁处理；所以扫描结束后没有代码差异，不能简单归结为工具没有识别漏洞。

项目资料称，补丁生成后还会验证修复效果及相关测试，用来判断补丁是否解决问题、有没有引入回归。但这只代表工具执行了相应验证，不代表项目全部测试必然通过；相关资料也没有给出固定的测试命令和通过标准。最终仍应查看差异并运行项目自己的测试：

git status --short
git diff

补丁验证完成后，再用 --create-pr 提交已验证文件并打开 GitHub Pull Request：

npx @openai/codex-security scan . --patch --patch-severity high --create-pr

这条命令有两层副作用：先修改本地代码，再向远端仓库提交内容并创建 PR。执行前应确认当前分支、提交身份、远端仓库和 GitHub 权限，避免把未审查的改动直接推到受保护分支。

如果补丁或 PR 没有生成，可以逐项核对 --patch、--patch-severity、--create-pr 是否组合正确，目标发现是否进入阈值，补丁是否完成验证，以及账号是否拥有仓库写入和创建 PR 的权限。当前资料没有提供这些场景的稳定错误码，不应凭报错文案猜测原因。

工具发布时仍是早期版本，官方表示会根据反馈继续改进；自动生成的补丁应当作为待审核的安全建议，而不是可以无条件合并的结论。网络可信访问审批仍可能影响部分请求。资料中还出现过 --mode deep、--workers 以及模型和 effort 参数，它们都不应在未经当前 --help 和仓库 README 确认的情况下写死进生产流水线。

最稳妥的下一步顺序是：检查 Node.js 与 Python 版本，确认 Codex Security 权限并完成认证，在仓库根目录完成一次本地扫描，验证 JSON 输出能否稳定解析，最后才启用 --patch、人工审查差异并尝试 --create-pr。这样可以把环境故障、扫描结果、补丁副作用和远端 PR 分开定位，避免一次把整条链路都推到自动提交阶段。