Codex Security CLI 快速入门

中文指南编辑组发布于 2026-07-31更新于 2026-07-31

Codex Security CLI 快速入门

Codex 中文站说明： 本页围绕“Codex Security CLI 快速入门”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

设置 Codex Security、运行本地扫描，并查看报告、发现结果和覆盖范围。

Codex Security 可帮助安全和工程团队查找、确认并修复漏洞。使用其命令行界面 (CLI) 扫描您拥有或获准评估的仓库、持续查看发现结果，并在变更合入前进行检查。

@openai/codex-security 软件包是公开的。运行扫描需要 Codex Security 访问权限。要在 Codex 中进行交互式扫描，请从 Codex Security 插件快速入门开始。有关已连接的 GitHub 仓库，请参阅 Codex Security 云端设置。

检查先决条件

CLI 需要 Node.js 22.13.0 或更高版本。运行扫描或导出发现结果还需要 Python 3.10 或更高版本。有关更多详细信息，请参阅身份验证和先决条件。

设置并验证 CLI

使用 npx 运行 CLI 并检查其版本：

npx @openai/codex-security --version

列出可用命令：

npx @openai/codex-security --help

另请参阅 CLI 参考。

准备扫描

选择要扫描的仓库以及用于写入结果的目录。

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

如果省略 --output-dir，Codex Security 会将结果保存在自己的持久状态目录中。结果可能包含源代码摘录和漏洞详细信息，因此请选择私有位置并采用适当的保留策略。

如果默认状态目录不可写，请在所扫描仓库之外选择一个可写目录：

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

开始扫描前，请检查仓库、目标和输出目录：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

试运行会检查本地输入，包括所有 --knowledge-base 路径，但不会启动 Codex、加载凭据或探测插件的 Python 解释器。

运行首次扫描

运行标准扫描，并将结果保存在所选目录中：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

交互式终端会显示实时扫描面板。添加 --headless 可改为显示纯文本进度行。CI 和没有交互式会话的终端会自动使用纯文本进度。

默认情况下，CLI 会将扫描进度和完成摘要写入 stderr。它不会将完整扫描结果输出到 stdout。扫描完成后会输出类似以下内容的摘要：

REPORT    /path/outside/repository/codex-security-results/report.md

FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
COVERAGE  complete
ELAPSED   42s
RESULTS   /path/outside/repository/codex-security-results

如果相关信息可用，还会显示 token 用量和预估成本。要输出完整的机器可读 JSON 结果，请明确请求结构化输出：

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json

扫描默认仅生成报告，因此发现结果会保留供本地审查。当您准备好在 CI 中运行扫描时，可以添加严重性阈值。

选择模型和推理强度

扫描默认使用 gpt-5.6-sol，推理强度为 xhigh。任务有需要时，可选择其他模型和强度：

npx @openai/codex-security scan "$REPOSITORY" \
--model gpt-5.6-terra \
--effort high

支持的强度级别包括 minimal、low、medium、high 和 xhigh。

查看结果

打开 report.md 查看易读的结果。扫描目录还包含供自动化使用的结构化文件：

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
└── results.sarif       # when produced

scan-manifest.json 记录目标、范围、生成方和密封制品。
findings.json 记录每个发现结果的严重性、置信度、位置、证据和修复措施。
coverage.json 记录已审查的界面、排除项、延期工作、待解决问题和覆盖完整性。

覆盖范围可以是 complete、partial 或 unknown。在将扫描视为审查证据之前，请阅读所有延期区域或待解决问题。 CLI 参考介绍了完整的制品和输出契约。

选择下一次扫描

当仓库包含独立的服务或软件包时，请使用路径扫描：

npx @openai/codex-security scan "$REPOSITORY" \
--path services/billing \
--path packages/auth

审查基础修订版本与 HEAD 之间已提交的变更：

npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

审查相对于 HEAD 的暂存和未暂存变更：

npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

差异和工作树扫描要求仓库参数为 Git 工作树根目录。开始差异扫描前，请获取所选修订版本。

当仓库或路径需要更广泛的审查时，请使用深度模式：

npx @openai/codex-security scan "$REPOSITORY" --mode deep

要控制发现工作进程、子智能体以及扫描停止时机：

npx @openai/codex-security scan "$REPOSITORY" \
--mode deep \
--workers 2 \
--subagents 0 \
--stop-after-no-new 3 \
--max-discovery-runs 10

这些选项需要深度模式。该模式支持仓库和路径目标，但不支持差异或工作树扫描。在这里，--workers 控制单次扫描内的发现工作进程；bulk-scan --workers 控制并发仓库扫描。

添加架构和安全上下文

提供架构文档、威胁模型或安全策略作为扫描上下文。这有助于 Codex Security 根据系统的实际工作方式评估发现结果：

npx @openai/codex-security scan "$REPOSITORY" \
--knowledge-base /path/to/architecture.md \
--knowledge-base /path/to/security-policies

添加自定义扫描说明

添加说明，让扫描聚焦于你的安全优先事项。可以使用第二个文件提供后续指令：

npx @openai/codex-security scan "$REPOSITORY" \
--scan-prompt-file /path/to/scan.md \
--post-scan-prompt-file /path/to/follow-up.md

后续指令会在同一个已验证身份的 session 中运行，适用于成功完成的扫描，也适用于覆盖范围不完整或出错的扫描；扫描被取消或达到成本上限后不会运行。这两个选项也适用于 bulk-scan；CSV 的 prompt 列可添加仓库专用说明。

设置扫描预算

使用 --max-cost 在预估模型成本超过以 USD 计价的限额时停止扫描：

npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

已在进行的请求可能会在略微超过限额后完成。如果扫描因成本限制而中止，部分扫描结果仍会保留在磁盘上。

在每次提交前扫描变更

为仓库安装 Git pre-commit 安全检查：

npx @openai/codex-security install-hook

该检查会在每次提交前扫描暂存和未暂存的变更。它会阻止高严重性发现结果和扫描错误，但不会替换现有的 pre-commit 脚本。

批量扫描仓库

发现仓库前，请登录 GitHub：

gh auth login

从您的 GitHub 账户或组织中发现并选择仓库：

npx @openai/codex-security bulk-scan

交互式流程会排除已归档仓库和 fork。扫描前，它会要求您确认所选仓库。

要扫描准备好的仓库列表，请提供 CSV 和输出目录：

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

再次运行相同命令即可恢复现有批量扫描。Codex Security 会跳过已完成的仓库。需要重试临时仓库错误或扫描错误时，请添加 --max-attempts 3。

有关 GitHub 发现、CSV 准备、活动结果和 Docker 设置，请参阅运行批量安全扫描。

在 Docker 中运行批量扫描

如果您的访问权限包含 Codex Security Docker 镜像，请在 Linux Docker 主机上使用随附的强化 Compose 配置和安全配置文件。主机必须支持创建非特权用户命名空间。请提供仓库 CSV，将结果和登录状态保存在持久挂载目录中，并通过环境或密钥管理器提供凭据：

docker compose run --rm codex-security \
bulk-scan /input/repositories.csv \
--output-dir /output \
--workers 4

容器会以无交互提示的方式运行批量扫描。如果希望以交互方式发现仓库，请在 Docker 外部使用 CLI。对于私有仓库，请通过环境或密钥管理器提供 GH_TOKEN 或 GITHUB_TOKEN。登录要求（包括账户和仓库访问权限）同样适用于容器化扫描。

重新查看已保存的扫描

列出仓库中保存的扫描：

npx @openai/codex-security scans list "$REPOSITORY"

从结果中复制扫描 ID，以检查其发现结果和配置：

npx @openai/codex-security scans show SCAN_ID

要检查某次扫描及其 workers 保存的事件：

npx @openai/codex-security scans logs SCAN_ID

保存的日志不会经过脱敏，可能包含源代码或凭据。分享前请先检查。

列出该仓库历次扫描中仍处于 open 状态的发现：

npx @openai/codex-security findings list "$REPOSITORY"

如果最新扫描没有确认某项较早的发现，该发现仍会保持 open 状态。

要将已审查的发现结果标记为误报，请说明该发现不适用的原因：

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
--reason "The route already checks permissions"

后续扫描会考虑该说明，但仍会重新检查当前代码。

使用原始配置对当前检出内容重新运行同一扫描：

npx @openai/codex-security scans rerun SCAN_ID

比较两次扫描，以查找新增、持续存在、重新出现、已解决或状态未知的发现结果：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较会自动按根本原因匹配发现结果，并复用已保存的匹配项。

有关批量扫描 CSV 格式、扫描历史筛选器和命令选项，请参阅 CLI 参考。

请继续选择符合您目标的工作流：

运行批量安全扫描，以发现 GitHub 仓库或扫描固定的 CSV 清单。
阅读 CLI 常见问题解答，了解扫描历史、误报反馈、覆盖范围和修复验证方面的答案。
在 CI 中运行扫描，以审查拉取请求、保留结果并设置严重性策略。
使用 CLI 参考，检查所有标志、输出格式、制品和退出代码。
集成 TypeScript SDK，从应用或开发者工具运行扫描。

本站实践建议

应用“Codex Security CLI 快速入门”中的安全设置时，应从最小权限开始，再根据实际任务逐步开放。涉及网络、密钥、生产环境或删除操作时，仍应保留人工确认。

Codex API 与国内使用

在实践“Codex Security CLI 快速入门”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。