Codex Security CLI 常见问题

查找有关从终端扫描仓库和管理安全结果的常见问题的答案。对于安装和首次扫描，请从 CLI 快速入门 开始。

仓库扫描

为什么登录后扫描仍使用 API key

当环境中包含 OPENAI_API_KEY 或 CODEX_API_KEY 时，没有交互式终端的扫描以及 JSON 和 JSONL 扫描默认使用环境变量中的 API key，即使你已经成功通过 ChatGPT 或 access token 登录。若 ChatGPT 登录也可用，使用文本输出的交互式扫描会询问要选择哪种凭据。试运行不会提示选择，也不会加载凭据。

如需在扫描中使用已存储的凭据，请显式选择：

npx @openai/codex-security scan . --auth chatgpt

要强制使用 OPENAI_API_KEY 或 CODEX_API_KEY 中的 API key：

npx @openai/codex-security scan . --auth api-key

如需让已存储的凭据成为自动选择的默认值，请运行 unset OPENAI_API_KEY CODEX_API_KEY。所有支持的认证模式请参阅 CLI 参考。

中断的批量扫描可以恢复吗

可以。使用原始 CSV 和输出目录运行相同的 bulk-scan 命令。 Codex Security 会跳过已完成的仓库。

添加 --max-attempts 3 以重试临时仓库或扫描错误：

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

已完成的扫描会保留结果，且不会重试，即使仍存在覆盖缺口 也是如此。覆盖缺口不会导致批量扫描任务以退出码 2 退出。

安全发现与覆盖范围

团队在哪里可以找到早期的扫描结果

列出仓库的已保存扫描：

npx @openai/codex-security scans list /path/to/repository

使用结果中的扫描 ID 来检查其结果：

npx @openai/codex-security scans show SCAN_ID

每次完成的扫描都会将其报告、结果、覆盖范围和支持产物保存在一起。有关完整布局，请参阅扫描产物。

要检查已保存的扫描及其 worker 事件，请运行 scans logs SCAN_ID。这些日志不会经过脱敏，可能包含源代码或凭据。

CLI 无法保存扫描历史记录时怎么办

Codex Security 会把扫描历史记录保存在工作台数据库中。如果默认状态目录不可写，请选择仓库之外的私有目录：

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

扫描如何区分新发现和已知发现

列出某个仓库所有扫描中仍处于 open 状态的发现：

npx @openai/codex-security findings list /path/to/repository

列表会标明最新扫描中已确认的发现，以及未在该次扫描中确认、但仍为 open 的较早发现。

比较两次扫描中的发现：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较会按根本原因自动匹配发现项，复用已保存的 匹配关系，并识别新增、持续存在、重新打开、未观测到、已解决和 未知的发现项。如果后续扫描在其扫描的代码中未找到先前的发现项， 该发现项的状态就是未观测到。只有将其 明确以已修复为由关闭后，才算已解决。被排除的路径和不确定的匹配关系仍 归为未知。

误报反馈如何发挥作用

检查已保存的扫描，找到安全发现的 occurrence ID：

npx @openai/codex-security scans show SCAN_ID

记录为什么该发现不适用：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

未来对同一仓库的扫描会将该解释作为上下文。这些扫描仍会独立检查当前源代码、控制措施和可达性。将发现标记为误报不会屏蔽规则、路径或漏洞类别。

有关命令的详细信息，请参阅安全发现参考。

为什么重复扫描会返回不同的结果

即使扫描配置相同，AI 辅助扫描的结果也可能不同。首先重新运行基线扫描：

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

重新运行时会保留原始扫描配置，并且要求使用相同的插件 版本。如果已安装的插件发生变化，该命令将停止。

将基准扫描与新扫描进行比较：

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

当缺少上下文可能导致变化时，提供共享架构和安全指导。匹配可以识别运行中相同的潜在发现，但它并不使扫描具有确定性。直接重新检查任何消失的重要发现。

团队如何确认修复是否有效

针对更改后的检出目录重新检查原始发现项。在该检出目录中， 传入原始发现项的报告以及要验证的问题：

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

审查相关证据，确认漏洞路径已被封堵，且正常行为 仍可正常运行。如果有原始复现程序或回归测试，请运行它们。 如果无法运行检查，请在结果中注明仍存在的不确定性。

扫描比较 可以显示发现项的变化，但仅凭某个发现项未再出现，无法验证修复是否有效。

覆盖不完全是什么意思

查看 coverage.json，了解被排除的路径、推迟审查的范围和待解答的问题。 新结果不包含覆盖完整性字段。查看 scan-manifest.json 中的 scan.status，了解执行状态。

覆盖缺口不会改变已完成扫描的退出码。退出码为 0 并不意味着 每个文件都经过了审查。如果后续扫描未覆盖先前发现项的原始路径， 就无法确定该发现项是否已不复存在。

自动化和成本

深度扫描的时间限制如何运作

启动深度扫描时设置工作进程的截止时间：

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

默认值为 96 小时。可以使用不超过 96 的任意正数，包括 小数。到达截止时间时，Codex Security 会停止未完成的工作进程，保留 已完成的标准扫描结果，并将其汇总到最终报告中。 查看报告，了解已审查的区域和推迟的工作。截止时间本身 不决定退出码；退出码由执行状态和严重级别策略决定。

对于持久化设置或批量扫描活动，请在深度扫描 配置的 [deep_scan] 下设置 max_time_hours。

扫描成本限制如何运作

在开始扫描之前设置以美元为单位的估计成本限制：

npx @openai/codex-security scan . --max-cost 5

该限制是估算值，并非严格的支出上限。已经在 进行中的请求完成时，费用可能超出该限制。如果深度扫描在 Codex Security 汇总已完成的工作进程结果后达到限制，CLI 可以保存一份已完成的 报告，并附带预算警告。它会返回 0；如果发现项达到 配置的严重级别阈值，则返回 1。如果无法生成有效的已完成结果， 则返回 2，并保留所有可用输出。

对于 GitHub PR检查和定时仓库扫描，请使用Codex Security GitHub Action。使用action-v0.3.0 时，扫描完成意味着所配置的分析生成了有效结果。排除的扫描范围和推迟的调查不会绕过严重性策略。请查看 coverage.json，以评估扫描的范围和局限性。如果还要拒绝空差异和试运行，请要求 Action 的scan-status 输出为 completed；请参阅选择严重性策略。

对于其他提供商，请参阅 CI/CD 概述。要在每次提交前执行检查，请使用install-hook。