Codex Security CLI 参考

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

使用此参考检查受支持的 codex-security 命令、标志、输出格式和退出行为。如需引导式的首次浏览，请从 CLI 快速入门开始。

该 @openai/codex-security 包是公开的。运行扫描需要 Codex Security 访问权限。

在你的项目中安装已发布的包：

npm install @openai/codex-security

以 npx @openai/codex-security调用已安装的包。当可执行文件在你的 codex-security 上可用时，你可以直接使用 PATH。

命令概览

usage: codex-security [--version] <command> [options]

该 CLI 提供这些命令：

命令	用途
`codex-security scan`	运行一次 Codex Security 扫描。
`codex-security install-hook`	安装 Git 预提交安全扫描。
`codex-security bulk-scan`	发现代码库并运行可恢复的批量扫描。
`codex-security scans`	列出、检查、匹配、重新运行和比较已保存的扫描。
`codex-security findings`	审查并更新已保存的安全发现。
`codex-security export`	将已完成的发现导出为 CSV、 JSON或 SARIF。
`codex-security validate`	检查一个或多个候选安全发现。
`codex-security patch`	修补一个或多个安全问题。
`codex-security login`	登录、存储凭据或检查登录状态。
`codex-security logout`	移除已存储的登录信息。
`codex-security info`	显示只读 SDK 和捆绑插件元数据。

该 CLI 还提供这些集成命令：

命令	用途
`codex-security completions`	生成 shell 补全脚本。
`codex-security mcp`	将 CLI 注册为 MCP 服务器。
`codex-security skills`	将 Codex Security 技能同步到 Agent。

列出所有可用命令：

npx @openai/codex-security --help

向命令添加 --help 以检查其参数和选项：

npx @openai/codex-security scan --help

codex-security --version 会打印已安装版本并退出。 codex-security info --json 会报告 SDK 和捆绑插件版本。这两个命令都不需要 Python。

发现命令并连接 Agent

打印 Agent 可读的命令清单：

npx @openai/codex-security --llms

将扫描参数架构检查为 JSON：

npx @openai/codex-security scan --schema --format json

为 Bash 生成 shell 补全：

npx @openai/codex-security completions bash

将 bash 替换为 zsh 或 fish 以用于这些 shell。

扫描结果支持 --format toon|json|yaml|jsonl 和 --full-output。这个框架级 --format 不同于 --export-format，后者用于选择从已完成扫描导出的工件格式。全局命令帮助也会列出 md，但扫描结果不支持 Markdown 输出。

将 CLI 注册为 MCP 服务器：

npx @openai/codex-security mcp add

将 Codex Security 技能同步到你的 Agent：

npx @openai/codex-security skills add

MCP 仅公开只读 info 元数据命令。扫描、导出、身份验证、验证和修补仍然仅限 CLI。

`codex-security scan`

针对代码库、选定路径、已提交更改或工作树运行扫描。

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository 默认为当前目录。

选择扫描身份验证

使用 --auth auto（默认值）自动选择凭据。当一个 ChatGPT 登录以及 OPENAI_API_KEY 或 CODEX_API_KEY 都可用时，带文本输出的交互式扫描会询问使用哪个凭据。 CI、 JSON 和 JSONL 扫描，以及其他没有交互式终端的扫描，会使用环境 API 密钥。空运行不会提示或加载凭据。

要使用你存储的凭据，请传入 --auth chatgpt：

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

要使用环境 API 密钥，请传入 --auth api-key：

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

要将已存储凭据设为自动默认值，请运行 unset OPENAI_API_KEY CODEX_API_KEY。

选择扫描目标

为每次扫描选择一种目标类型。

参数	描述
`--path PATH`	扫描相对于代码库的路径。可重复该标志以添加更多路径。
`--diff BASE`	扫描从 `BASE` 到 `--head`的已提交更改。head 默认为 `HEAD`。
`--head HEAD`	为 `--diff`设置 head 修订版本。
`--working-tree`	针对 `--base`扫描已暂存和未暂存的更改。base 默认为 `HEAD`。
`--base BASE`	为 `--working-tree`设置 base 修订版本。
`--mode {standard,deep}`	选择扫描模式。默认值为 `standard`。

--path、 --diff和 --working-tree 互斥。 --head 需要 --diff，而 --base 需要 --working-tree。深度模式支持代码库和路径目标。

差异和工作树扫描要求代码库参数是 Git 工作树根目录。选定的 ref 必须存在于该检出中。

扫描整个代码库：

npx @openai/codex-security scan .

扫描选定路径：

npx @openai/codex-security scan . --path src --path tests

扫描已提交更改：

npx @openai/codex-security scan . --diff origin/main --head HEAD

扫描已暂存和未暂存的更改：

npx @openai/codex-security scan . --working-tree --base HEAD

对代码库运行更深入的审查：

npx @openai/codex-security scan . --mode deep

添加安全上下文

使用 --knowledge-base PATH 提供架构文档、威胁模型、或安全策略。重复该选项可添加更多文件或目录：

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

支持的文档包括 .md、 .markdown、 .txt、 .pdf和 .docx 文件。该 CLI 会递归搜索目录，拒绝链接输入路径，跳过链接目录条目，并将提取的文档内容保留在已保存扫描结果之外。

设置输出和策略选项

使用这些选项来保留工件、保留先前结果，或创建机器可读的结果。

参数	描述
`--output-dir DIR`	将扫描工件写入包围 Git 工作树之外的私有目录。默认为持久 Codex Security 状态。
`--archive-existing`	将现有结果移动到 `DIR.previous-<timestamp>-<id>` 并以空输出目录开始。需要 `--output-dir`。
`--fail-on-severity LEVEL`	当已完成扫描报告的发现达到或高于 `1` 、 `critical`、 `high`或 `medium`时，返回退出 `low`。
`--max-cost USD`	当估算的模型成本超过指定的 USD 金额时停止扫描。
`--dry-run`	在不启动扫描的情况下检查代码库、目标、输出目录和 Codex 配置。
`--json`	将清单、发现、覆盖范围、路径和轮次元数据作为一个 JSON 文档打印。
`--format FORMAT`	将完整扫描结果打印为 `toon`、 `json`、 `yaml`或 `jsonl`。
`--full-output`	使用默认结构化输出格式打印完整结果。

成本限制是估算值，不是严格的支出上限。已在进行中的请求可能会在超过限制后完成，部分扫描结果仍然可用。

当你省略 --output-dir时，结果会持久保存在 $CODEX_HOME/state/plugins/codex-security/scans/<repository>下。 CODEX_HOME 默认为 ~/.codex。设置 CODEX_SECURITY_STATE_DIR 可改为将结果保留在 $CODEX_SECURITY_STATE_DIR/scans/<repository> 下。这些目录可能包含源代码摘录和漏洞详情，因此请相应管理其权限和保留期限。

工作台会将扫描历史保存在 $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3中。设置 CODEX_SECURITY_STATE_DIR 也会移动工作台数据库。

输出目录必须位于被扫描目录以及任何包围它的 Git 工作树之外。扫描可以用 --archive-existing替换现有结果目录。

要在复用输出目录前保留先前结果：

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

默认情况下，扫描仅生成报告。添加 --fail-on-severity 以在中评估 CI严重性策略：

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

空运行会检查本地输入，而不加载凭据、启动 Codex，或探测插件的 Python 解释器：

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

配置运行时

当你需要显式指定模型、解释器、插件或 Codex 配置值时，请使用运行时选项。

参数	描述
`--auth {auto,chatgpt,api-key}`	选择扫描凭据。默认值为 `auto`。
`--model MODEL`	选择 OpenAI 模型。默认值为 `gpt-5.6-sol`。
`--effort {minimal,low,medium,high,xhigh}`	选择模型的推理强度。默认值为 `xhigh`。
`--plugin-path PATH`	使用 Codex Security 插件目录或 ZIP 来覆盖捆绑插件。
`--python PATH`	为插件运行时选择 Python 解释器。
`--codex KEY=VALUE`	覆盖隔离的 Codex 配置值。值使用 TOML 语法。重复该标志可添加更多值。

要在不写入 TOML的情况下选择不同模型和推理强度：

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

对通过 --codex 传入的字符串值加引号，以便 TOML 解析器接收字符串：

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

`codex-security install-hook`

为当前代码库安装 Git 预提交安全检查：

npx @openai/codex-security install-hook

该检查会在每次提交前扫描已暂存和未暂存的更改，并阻止高严重性发现或扫描错误。它遵循 core.hooksPath 并且不会替换现有的 pre-commit 脚本。可在需要时设置不同的严重性阈值：

npx @openai/codex-security install-hook . --fail-on-severity medium

`codex-security bulk-scan`

发现并扫描 GitHub 代码库，或从代码库 CSV运行可恢复扫描：

有关 GitHub 发现、 CSV 清单、活动结果和容器化扫描的完整指南，请参阅运行批量安全扫描。

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

不带参数运行 npx @openai/codex-security bulk-scan 以交互方式选择代码库。此流程需要 GitHub CLI 登录。

要在交互式发现期间选择模型和推理强度：

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

对于准备好的代码库列表，请提供 CSV 和 --output-dir：

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

该 CSV 需要 id、 repository和 revision 列。修订版本必须是完整提交哈希。可选的 scope 和 mode 列用于配置单个代码库：

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers 限制同时扫描数，默认值为 4。 --mode 默认为 standard，且 --max-attempts 默认为 1。当 --max-attempts 你想在出错后重试某个代码库时，请设置。再次运行相同命令可从现有输出目录恢复批量扫描。该 CLI 仅在已完成代码库的已记录结果工件仍然存在时才会跳过它们。

对于容器化活动，请参阅在 Docker 中运行批量扫描。

`codex-security scans`

查找已保存的扫描

列出当前目录的已保存扫描：

npx @openai/codex-security scans

列出其他代码库的扫描：

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

查找存储在特定输出目录下的扫描：

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

检查或重复扫描

显示已保存扫描的结果和配置：

npx @openai/codex-security scans show SCAN_ID

使用原始配置针对当前检出重新运行扫描：

npx @openai/codex-security scans rerun SCAN_ID

匹配和比较发现

匹配两次扫描中具有相同根本原因的发现：

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较已匹配的扫描，以找出新增、持续存在、重新出现、已解决和未知的发现：

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

当较新的扫描覆盖范围不完整，或没有覆盖发现的原始位置时，该发现为未知。当你需要 --force 重新计算现有匹配时，请向 match 添加。

要匹配当前代码库的所有已完成扫描，包括来自其他检出的扫描：

npx @openai/codex-security scans match --all

即使重新运行相同配置，扫描结果也可能不同。匹配和比较用于跟踪变化；它们不会让结果具备确定性，也不能证明某个漏洞已不再存在。请使用 validate 针对当前代码重新检查安全关键的发现。

`codex-security findings`

将已审查的发现记录为误报：

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

检查已保存的扫描以识别发现的出现位置：

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"

原因不能为空。 Codex Security 会为该仓库保存此决定，并将其作为上下文提供给后续扫描。每次扫描都会独立重新检查当前源码、控制措施和可达性。先前的决定不会抑制某条规则、路径或漏洞类别。

`codex-security export`

从已完成且已密封的扫描中导出 CSV、 JSON，或 SARIF 。导出会在写入输出前验证扫描产物，并保持 Codex 运行时和凭据不变。

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir 是已完成的扫描目录。

参数	说明
`--export-format {csv,json,sarif}`	选择导出格式。默认值为 `sarif`。
`--output FILE\|-`	将所选格式写入文件或 stdout。默认写入当前目录中的文件。
`--source-root PATH`	使用仓库检出向 SARIF 添加源代码行指纹。
`--python PATH`	为内置导出器选择 Python 解释器。

--source-root 仅适用于 --export-format sarif。 JSON 会保留已密封的发现文档。 CSV 包含可移植的发现列，且不包含本地工作台分诊状态。

如果没有 --output，则 CLI 会将 SARIF 写入 results.sarif， JSON 写入 findings.json，并将 CSV 写入 findings.csv 当前工作目录中。导出内容可能包含源码摘录和漏洞详情。请在仓库外运行该命令，或传入 --output 并使用位于已扫描检出目录之外的私有路径。

将 SARIF 写入文件：

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

将 SARIF 写入 stdout：

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

将发现导出为 JSON：

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

将发现导出为 CSV：

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

`codex-security validate` 和 `codex-security patch`

检查候选发现是否有效：

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

使用内置修复技能生成修复：

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

每个参数都可以包含字面文本或指向文件。两个命令都针对当前目录运行。使用 validate 在修复后或后续扫描不再报告时，直接重新检查原始发现。仅凭扫描比较无法证明修复已生效。外部工具可以使用这些命令，而无需重新构建扫描器。

使用 --effort 为任一命令选择推理强度：

npx @openai/codex-security validate "Possible SQL injection" --effort high

`codex-security login`、 `logout`，以及 `info`

以交互方式登录：

npx @openai/codex-security login

在远程或无头机器上使用设备认证：

npx @openai/codex-security login --device-auth

检查当前登录状态：

npx @openai/codex-security login status

移除已存储的登录信息：

npx @openai/codex-security logout

通过 stdin 传入以存储 API 密钥：

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

存储企业访问令牌：

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

检查只读 SDK 和内置插件元数据：

npx @openai/codex-security info --json

当你将 CLI 公开为 MCP 服务器时， info 是唯一可用的命令。扫描、导出、登录、验证和打补丁仍然 CLI仅限使用。

读取扫描输出

默认情况下，扫描会将进度、完成摘要和错误发送到 stderr，而不会将完整扫描结果写入 stdout。请求 --json、 --format，或 --full-output 以将结构化扫描结果发送到 stdout。

完成摘要

已完成的扫描会将发现数量、严重性细分、覆盖范围、耗时、报告路径和结果目录写入 stderr。可用时还会包含 token 用量和估算成本：

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

信息性发现会计入摘要总数。严重性策略仅评估 critical、 high、 medium和 low 发现。

JSON 输出

scan --json 会向 stdout 写入一个完整的 JSON 文档。其顶层结构为：

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

进度、完成摘要、归档通知和错误仍会输出到 stderr。当严重性策略 JSON 返回退出码或覆盖范围不完整返回退出码 1 时，已完成的扫描仍会打印完整的 2结果。

codex-security scan --json 会发出一个 JSON 文档。 codex exec --json 会发出 JSON Lines 事件流。请使用与你运行的命令相匹配的输出格式。

扫描产物

已完成的扫描会将可读报告和结构化产物保存在一起：

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

这些结构化文件承担不同作用：

文件	内容
`scan-manifest.json`	扫描身份、状态、目标、范围、生成方和已密封产物记录。
`findings.json`	发现标识符、严重性、置信度、分类、位置、证据、验证、数据流、可达性和修复。
`coverage.json`	已审查的表面、排除项、推迟的工作、未决问题和覆盖完整性。
`report.md`	可读扫描报告。
`artifacts/`	支持性扫描产物。
`exports/results.sarif`	SARIF 扫描期间生成（如存在）。

覆盖完整性有三个值：

complete：扫描记录其所选范围的完整覆盖。
partial：扫描记录推迟的工作或其他覆盖限制。
unknown：扫描将覆盖完整性报告为未知。

在将覆盖范围用作安全决策证据之前，请审查推迟的表面、明确排除项和未决问题。

退出码和信号

该 CLI 使用以下退出码：

退出码	条件
`0`	扫描已完成且覆盖范围完整，并通过其严重性策略；批量扫描已完成且没有失败；或其他命令成功。
`1`	已完成的扫描报告了达到或高于配置严重性的发现。
`2`	该 CLI 发现输入、运行时或导出错误；扫描覆盖范围不完整；或批量扫描中有仓库出错。
`130`	Ctrl-C 中断了扫描。
`143`	SIGTERM 终止了扫描。

任何具有 partial 或 unknown 覆盖范围的扫描都会返回 2，即使没有严重性策略。请求结构化输出时，已完成的扫描仍会将可用结果写入 stdout。该 CLI 会在中断或运行时错误后打印任何部分输出的位置。

认证和先决条件

设置 OPENAI_API_KEY 或 CODEX_API_KEY，使用 npx @openai/codex-security login登录，或使用现有的基于文件的 Codex 登录信息。

有关凭据选择，请参阅选择扫描认证。

对于 CI，请将 API 密钥限定在扫描步骤范围内，并使用受信任的工作流。

该 CLI 需要 Node.js 22 或更高版本。运行扫描或导出发现还需要 Python 3.10 或更高版本。Python 3.10 还需要 tomli。自动发现不适用时，请使用 --python 或 PYTHON 选择解释器。

继续阅读 CLI 快速入门、批量扫描指南、 CLI FAQ、 CI 指南，或 TypeScript SDK 指南。

纯文本别名

–output FILE|-