Codex Security 是一款安全智能体,用于查找代码中可能存在的漏洞,核实证据,并推动修复。首先要区分两者:在本地 Codex 中使用的插件,以及连接 GitHub、在云端运行的 Codex Security Cloud。两者名称相似,但设置方式、运行位置和查看费用的地方都不同。另外还有一个独立的命令行版本,用于集成到 CI 等流程中(@openai/codex-security,以下称“独立 CLI”)。

想检查本地代码

Codex Security

在桌面应用或 Codex CLI 聊天中运行。可从整个仓库、指定文件夹或变更差异中选择要检查的范围。

想持续关注 GitHub 上的变更

Codex Security Cloud

这是另一个插件。它在云端检查已连接的 GitHub 仓库,可以进行单次扫描,也可以监控新的提交。

本文将整理如何选择、费用与免费额度、首次扫描、深度检查的负担、如何阅读结果,以及修复后的确认方法。

来源:OpenAI Codex Security 概览与本地插件的入门步骤。

本地版、Cloud 版与常规审查的选择

如果只是检查小的改动,也可以把差异和审查条件直接交给普通的 Codex。但这并不意味着会自动附带专用扫描器的输出,或检查范围的记录。“请审查代码”和运行 Codex Security 扫描应当分开看待。关于 Codex 各产品本身的区别,请参阅 Claude Code 与 Codex 比较文章。

检查功能或实现的差异使用普通 Codex 审查,并指定要检查的要点,例如规格、测试、可读性等。如果以安全为主题,可以考虑使用专用的 Changes 扫描。
扫描本地仓库使用 Codex Security 插件进行 Codebase 扫描。大型仓库可以把范围缩小到责任和归属明确的服务或文件夹。
监控 GitHub 提交使用 Codex Security Cloud 的持续扫描。需要确认 GitHub 连接、使用权限、云端环境,以及与常规使用额度分开计算的计费条件。
集成到 CI 或自有工具中已公开独立 CLI(@openai/codex-security)和 SDK。它们与 Codex CLI 内的插件是不同的产品,因此请分别确认认证方式、执行权限和预算。

Cloud 目前处于研究预览阶段,使用时需要目标工作区的访问权限。独立 CLI 也是如此:软件包已公开,与账户拥有扫描权限是两回事。根据账户和仓库的不同,全面扫描可能还需要“Trusted Access for Cyber”。不能仅凭 Pro 等套餐名称,就判断所有路径都可以使用。如果界面上没有显示相应功能,请检查插件是否已启用、使用权限以及组织的管理设置。

来源:OpenAI 概览与访问条件与代码变更的安全审查。

费用与免费额度:Pro 仍需单独确认

Cloud 扫描不计入常规套餐的使用额度

OpenAI 的 Cloud 常见问题说明,2026 年 10 月 1 日 12:53(美国太平洋时间)及之后设置的仓库扫描与持续扫描,将根据套餐的 token 费率以积分或美元计费。它们不计入常规套餐的使用额度。符合条件的账户,免费扫描积分会先于付费使用被消耗。

在上述时间之前已设置持续监控

符合条件的现有监控在 10 月 21 日前免费

之后新增的扫描不在此列。免费期结束后,若启用付费使用则继续,未启用则暂停。

在上述时间之前没有设置持续监控

符合条件的账户可获得相当于 500 美元的免费额度

适用于符合条件的账户。单次扫描与持续扫描使用同一余额,并在工作区内共享。根据常见问题,该免费扫描积分没有有效期。

500 美元是面向符合条件账户的扫描积分。用完之后,将适用该账户或工作区的计费方式。开始前,请在界面上确认自己是否符合条件、还剩多少免费额度,以及付费使用的条件。

界面上的“费用”不一定是实际收费金额

在 Cloud 中,可从“Scans”打开目标扫描,查看 token 数量和费用。将光标移到 token 数上,会显示输入、缓存输入和输出的明细。显示的费用是在应用免费额度或免收费用之前的金额,因此要把免费额度的抵扣与实际收费分开看。显示“Exempt from billing. No charges apply.”的扫描不收费。

费用、免费额度和显示方式的来源:OpenAI Codex Security Cloud 常见问题“Billing”。时间基准为官方记载的美国太平洋时间。

不要把 Cloud 的免费额度套用到本地版

本地插件作为 Codex 任务运行。根据 Codex 的通用使用条款,套餐、模型、处理量和认证方式都会影响消耗;使用 API 密钥进行的额外本地工作,则按 API 费率计费。另一方面,在已确认的本地入门步骤、Standard 与 Deep 扫描说明以及 CLI 常见问题中,没有每次扫描的固定价格,也没有插件专属的价格表。请不要认为“本地就是零消耗”,或“可以使用 Cloud 的 500 美元额度”。

即使已登录,独立 CLI 也可能使用 API 密钥。如果环境中存在 OPENAI_API_KEY 或 CODEX_API_KEY,在非交互式以及 JSON/JSONL 输出的扫描中,会默认选择该密钥。若同时存在环境 API 密钥和已保存的 ChatGPT 登录,交互式和文本输出模式会询问使用哪一种。官方提供了 --auth chatgpt 与 --auth api-key 的显式指定方式,因此请在开始前确定由谁付费。

可在用量界面查看 Codex 的剩余额度,在 Codex CLI 中则可使用 /status。Cloud 扫描的费用也需要在 Cloud 端确认。套餐对比请参阅 Pro 的价格与使用额度文章。

来源:OpenAI Codex/Work 的价格与用量、CLI 的认证选择。

首次扫描的步骤与提示词

以下是官方步骤的概要。扫描对象仅限于您拥有或已获得检查许可的代码。首次扫描时,请确认目标分支、修订版本、输出位置以及要使用的认证方式。从 Standard 开始是最容易理解的顺序。

桌面应用中的本地插件

  1. 在插件列表中找到“Codex Security”,安装并启用。Cloud 版是另一个插件。
  2. 打开侧边栏中的“Security”→“Scans”→“+ Scan”。
  3. 选择仓库。全面检查请选择“Codebase”;首次运行请关闭“Deep scan”。
  4. 确认要检查的文件夹、当前分支和修订版本,以及模型和推理强度。
  5. 仅在需要时,在“Additional context”中补充公开入口、授权条件和重要操作。
  6. 点击“Start scan”开始,查看各阶段的进度,完成后阅读检查范围和证据。

在 Codex CLI 中使用时,用 /plugins 安装,再用 /new 为目标仓库新建聊天。比起只说“看看安全性”,明确指出要使用专用扫描并说明对象,才能留下请求内容的记录。

请使用 Codex Security,以 services/billing 为重点进行标准扫描。
请优先检查用户输入、账单信息的所有者验证,以及仅限管理员的操作。
本次仅进行检查与报告。请不要修改源代码、commit、push、发布,或更改计费设置。
请报告所检查的修订版本、检查范围、被排除或未完成的范围,以及复现的证据。
如果需要更改设置,请说明更改内容和原因后停止。

写在提示词里的禁止事项,并不像沙箱那样强制限制权限。执行权限需要另行确认。

使用 GitHub 的 Cloud 版

  1. 安装“Codex Security Cloud”,并确认与目标仓库的 GitHub 连接。
  2. 在“Scan”中选择仓库和环境。“Auto”会在开始时创建环境;若要使用已准备好的环境,请在“Customize”中确认。
  3. 如果只想检查一次,选择“One-Time Scan”;如果要监控今后的提交,选择“Continuous Scanning”。
  4. 确认费用、免费余额和对象后,点击“Create”开始。

持续扫描以仓库的默认分支为对象。回溯的历史提交时间段越长,首次检查所需的时间越长。要停止监控,请在“Repositories”→目标仓库→“Monitoring settings”中暂停并保存。注意不要把关闭页面误当成停止监控。

来源:OpenAI 插件的入门步骤与Cloud 的设置与监控。

Standard 与 Deep:调整范围与负担

先建立基准

Standard

常规的仓库或文件夹扫描。先确认检查哪些内容、会得到什么样的证据,并以此作为之后检查的比较基准。

进一步检查所需的范围

Deep

为了更广泛地探索,会耗费较多时间和资源的方式。它使用彼此独立运行的检查工作进程,以及其下属的子智能体,并按条件汇总结果。

官方的 Deep 设置中,默认同时运行的工作进程数为 4,每个工作进程的子智能体数为 3,最长运行时间为 96 小时。96 小时是设置上的上限,而不是通常的运行时间。设置时间限制需要插件 0.1.19 或更高版本。达到时间限制时,未完成的工作进程会被停止,已完成的结果会被汇总。仍未检查的部分,该范围将保持未检查状态。

建议先把对象缩小到有意义的服务单位,阅读 Standard 的结果后,再判断是否需要 Deep。也可以只针对支付、认证等关键领域进行深入检查。降低工作进程数和时间限制可以减轻负担,但可能会有更多问题未被发现,因此需要记录“以更低成本、更快速度完成的结果覆盖了哪些范围”。

要检查差异时,使用“Changes”。可以选择未提交的变更、单个提交,或基准与目标修订版本,但Changes 中无法使用 Deep。它检查的是与差异直接相关的代码,也不会自动扩展为全面审计。

独立 CLI 的费用限制是估算值。官方的 --max-cost 会根据以美元折算的估算费用决定是否停止。已在进行中的请求可能会超出上限后才完成,因此它并不是严格的付款上限。请将其与时间限制、并行数和检查范围结合使用,不要把中途停止的检查当作完整结果。

来源:OpenAI Standard 与 Deep、默认值、Changes 的范围与估算费用限制。

读懂范围与证据,而非只看发现数量

仅凭“发现了多少个问题”,无法判断检查的好坏。检查对象错误、中途停止,或者不了解授权条件的检查,即使结果为零,也不能让人放心。官方的标准扫描步骤同样指导先阅读修订版本、已检查的领域、被推迟的领域以及每一项证据。

  1. 对象是否正确确认仓库、修订版本和范围。不要把旧代码的结果当作当前版本的保证。
  2. 哪些内容未被检查确认被排除、暂缓和中途终止的领域。不要因为显示“已完成”,就认为已经检查了全部内容。
  3. 证据是否成立确认从输入到危险处理的路径、现有防护,以及复现方法和结果。
  4. 是否需要修复考虑实际可触发的条件和影响,然后逐一修复已采纳的问题。

最容易入手的是 report.md。结构化的 coverage.json 用于确认已检查的领域和暂缓的部分,findings.json 用于确认每个问题的位置、严重程度、证据和修复方向。findings/ 中可能包含详细报告和复现文件。分享时请不要只拿出报告,应将相关文件一并保存。

阅读问题的示例(虚构):可以获取他人的账单信息

仅有“没有授权”这样一句话,判断材料不足。需要确认目标端点、登录条件、更改账单信息 ID 后的表现、所有者验证的位置,以及在其他层执行的检查。

成立的例子:在获得许可的验证环境中复现了:使用其他用户的 ID 可以返回数据。

需要继续调查的例子:处理之前可能仍存在所有者验证,而实际的调用路径和设置尚未得到确认。

在独立 CLI 中,请通过 coverage.json 确认未检查的范围(被排除的路径和被推迟的位置)。即使存在未检查的范围,退出码也不会改变,因此退出码 0 并不代表检查了所有文件。如果之后的扫描中问题消失,但没有检查原始路径,则不能判定为“已修复”。Cloud 的自动验证功能也只是尝试复现问题的功能,“未验证”的结果并不意味着“已证明安全”。

来源:OpenAI 标准扫描的评估步骤、CLI 的检查范围与对比与Cloud 的自动验证。

修复、重新验证与敏感信息处理

告诉扫描授权条件,有助于判断报告

在扫描的背景信息中,请写明“谁应该能够执行什么操作”。例如“账单信息仅限本人和管理员访问”或“文件只能由所有者公开”。对于本地插件,可以把 SECURITY.md 用作持续的安全策略,把 AGENTS.md 用于构建和验证步骤等指示。在 Cloud 中,请审查生成的威胁模型,并补充公开入口、关键操作和信任边界的缺失部分。

威胁模型是对应用结构和需要保护的条件的简短说明。Cloud 中的编辑会应用于之后的扫描,因此仅修正前提假设,并不会改变旧报告的检查内容。

每次只修复一个问题,并同时确认复现与正常行为

  1. 采纳问题:确认证据和实际影响,选定要修复的一个问题。
  2. 生成小型修复方案:在本地 UI 中选择“Patch”→“Generate patch”。生成方案与应用到目标检出目录是不同的步骤。
  3. 阅读差异:确认是否包含无关的整理,或削弱了其他防护的更改,然后用“Apply patch”应用。
  4. 重新验证:使用“Verify fix”确认原始复现步骤和正常行为。如有可能,还应保留一个修复前失败、修复后通过的回归测试。
  5. 关闭问题:仅仅验证并不会自动关闭问题。请阅读剩余的证据不足之处,然后附上理由关闭,或继续调查。

Cloud 提供修复方案时,也需要先确认内容,再创建草稿 PR。请分别记录:是否有修复方案、是否已应用、是否已重新验证、是否已发布到生产环境。同时请配合使用 AI 生成应用的上线前检查,不要把所有判断都交给单一的扫描器。

“本地”并不代表零外部传输

即使是在本地运行的路径,发送给模型的推理请求以及用于验证的信息,也需要另行确认。独立 CLI 的官方步骤提醒:扫描会使用本地操作系统权限,不会因每次操作的确认而停止,并且可能继承环境变量。不要断定它与普通 Codex 聊天具有相同的权限,请准备一个不包含不必要凭据的检查环境。

保存的日志不一定会自动删除敏感值,其中可能包含源代码或凭据。成果物中还包括复现方法和漏洞细节,因此在发布公开链接或与第三方共享之前,请确认内容和共享范围。关于模型改进的使用设置,请参阅另一篇文章 ChatGPT 与 Codex 的训练使用和隐私。

来源:OpenAI SECURITY.md 与 AGENTS.md、Cloud 威胁模型、修复与验证,以及独立 CLI 的权限、成果物和日志。

开始前的检查清单

  • 路径:确定使用本地插件、Cloud 还是独立 CLI。
  • 权限:确认代码的检查许可,以及账户的扫描权限。
  • 费用:不要混淆常规使用额度、Cloud 免费额度和 API 计费。
  • 对象:固定修订版本和范围,并优先考虑 Standard。
  • 判断:阅读的是检查范围、复现证据和剩余的不确定性,而不只是数量。
  • 修复:逐一确认每个差异和重新验证后,再采纳修复。

如果是第一次使用,可以先对所需范围执行 Standard 扫描,确认自己能否判断结果。需要持续监控时考虑 Cloud;想把扫描集成到自动化流程中时,考虑独立 CLI。它应作为补充问题发现与验证的工具,而不能替代现有的静态分析(SAST)或人工审查,也不能作为安全证明。

本文前提:本文于 2026 年 10 月 7 日依据 OpenAI 官方文档撰写,免费期和 CLI 退出码已于 10 月 19 日对照官方常见问题重新确认。我们未运行该产品的扫描,因此检测精度、耗时和消耗量,请您在自己仓库的一部分上试用后自行确认。

常见问题

问:如果订阅了 ChatGPT Pro,Codex Security Cloud 是否无需额外付费?

文档中并未说明它包含在常规套餐的使用额度之内。Cloud 扫描会按 token 费率计费;另外,还有符合条件的扫描免费积分,以及现有持续监控的免费期。请不要只看套餐名称,应确认自己的余额和付费使用的条件。

问:只让普通 Codex 帮忙审查代码还不够吗?

取决于目的。普通审查可以检查实现和测试。如果需要专用的检查范围、问题列表、复现证据和持续监控,可以考虑 Codex Security。

问:如果扫描结果为零个问题,就可以认为代码是安全的吗?

不能。请先确认修订版本、对象范围、是否中途终止,以及排除了哪些领域。如果检查范围不完整,或无法掌握业务上的授权条件,可能会遗漏问题。请与现有的静态分析和人工确认一起使用。

问:选择 Deep 扫描,是否就能在较少的使用额度下可靠地完成检查?

没有这样的保证。Deep 探索范围更广,因此比 Standard 耗费更多时间和资源。请调整对象、并行数和时间限制,并在扫描停止时阅读其已覆盖的范围。独立 CLI 的估算费用限制同样不是严格的付款上限。