Codex Security CLI 参考

查阅 Codex Security CLI 的命令、OpenAI 与 Amazon Bedrock 提供商、认证方式、输出格式、扫描产物和退出码，以及 scan、bulk-scan、export 等命令。

Codex Security CLI 参考#

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

Codex Security CLI 的参数、输出格式、扫描工件、提供商和退出代码。

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

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

使用 npx @openai/codex-security 运行 CLI。

命令概览#

text

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 技能同步到智能体。

列出所有可用命令：

bash

npx @openai/codex-security --help

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

bash

npx @openai/codex-security scan --help

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

发现命令并连接智能体#

输出智能体可读的命令清单：

bash

npx @openai/codex-security --llms

以 JSON 格式检查扫描参数架构：

bash

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

为 Bash 生成 shell 补全：

bash

npx @openai/codex-security completions bash

如需用于相应的 shell，请将 bash 替换为 zsh 或 fish。

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

将 CLI 注册为 MCP 服务器：

bash

npx @openai/codex-security mcp add

将 Codex Security 技能同步到智能体：

bash

npx @openai/codex-security skills add

MCP 仅公开只读的 info 元数据命令。扫描、导出、认证、验证和修复仍只能通过 CLI 完成。

`codex-security scan`#

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

text

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
[--provider {openai,openrouter,fireworks,amazon-bedrock}]
[--path PATH | --diff BASE | --working-tree]
[--head HEAD] [--base BASE]
[--knowledge-base PATH] [--scan-prompt-file FILE]
[--post-scan-prompt-file FILE]
[--mode {standard,deep}] [--workers N]
[--subagents N] [--stop-after-no-new N]
[--max-discovery-runs N] [--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] [--headless] [--verbose]
[--json] [--format {toon,json,yaml,jsonl}]
[--full-output] [repository]

repository 默认为当前目录。

选择扫描认证方式#

使用默认选项 --auth auto 可自动选择凭据。当 ChatGPT 登录信息和 OPENAI_API_KEY 或 CODEX_API_KEY 均可用时，采用文本输出的交互式扫描会询问要使用哪种凭据。CI、JSON 和 JSONL 扫描以及其他没有交互式终端的扫描会使用环境 API key。试运行不会提示或加载凭据。

如需使用已存储的凭据，请传入 --auth chatgpt：

bash

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

如需使用环境 API key，请传入 --auth api-key：

bash

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

如需将已存储的凭据设为自动选择时的默认值，请运行 unset OPENAI_API_KEY CODEX_API_KEY。

使用 OpenRouter 或 Fireworks#

使用其 API key 和显式模型选择 OpenRouter：

bash

export OPENROUTER_API_KEY="your-openrouter-api-key"
npx @openai/codex-security scan . \
--provider openrouter \
--model anthropic/claude-sonnet-4.5

使用其 API key 和显式模型选择 Fireworks：

bash

export FIREWORKS_API_KEY="your-fireworks-api-key"
npx @openai/codex-security scan . \
--provider fireworks \
--model accounts/fireworks/models/qwen3-235b-a22b

这两个提供商也支持 bulk-scan。

使用 Amazon Bedrock#

使用 --provider amazon-bedrock 选择 Amazon Bedrock，并通过 --model 指定显式的 Bedrock 模型：

bash

npx @openai/codex-security scan . \
--provider amazon-bedrock \
--model openai.gpt-5.6-sol

设置 AWS_REGION，并使用 AWS_BEARER_TOKEN_BEDROCK、标准 AWS 访问密钥、AWS 配置文件、Web 身份、容器凭据或默认 AWS 凭据链进行认证。Bedrock 扫描使用 AWS 凭据，而不是 --auth、ChatGPT 登录信息或 OpenAI API key。scan 和 bulk-scan 均支持 --provider。

选择扫描目标#

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

参数	说明
`--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 必须存在于该检出中。

扫描整个仓库：

bash

npx @openai/codex-security scan .

扫描选定路径：

bash

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

扫描已提交的更改：

bash

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

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

bash

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

对仓库运行更深入的审查：

bash

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

配置深度扫描#

将以下选项与 --mode deep 配合使用，以控制发现并发数和运行时间：

参数	说明
`--workers N`	并发发现工作进程的上限。默认为自动选择。
`--subagents N`	每个发现工作进程可用的子智能体。默认为 `3`。
`--stop-after-no-new N`	连续 `N` 次运行未发现新问题后停止。默认为 `6`。
`--max-discovery-runs N`	发现运行总次数的上限。默认为 `60`。

--subagents 接受零或正整数。其他选项要求使用正整数。这些选项不适用于标准扫描。

例如，将深度扫描限制为两个发现工作进程和总计十次运行：

bash

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

在 ~/.codex/codex-security/config.toml 中设置持久默认值；如果设置了 CODEX_HOME，则在 $CODEX_HOME/codex-security/config.toml 中设置：

toml

[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10

命令行选项会覆盖这些默认值。scan --workers 控制单次扫描内的发现工作进程；bulk-scan --workers 控制并发的仓库扫描。

添加安全上下文#

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

bash

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

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

添加扫描指令#

如需添加扫描指令，请使用 --scan-prompt-file 提供文本或 Markdown 文件。使用 --post-scan-prompt-file，可以在成功完成的扫描，以及覆盖范围不完整或出错的扫描后，在同一个已认证 session 中运行后续指令：

bash

npx @openai/codex-security scan . \
--scan-prompt-file security-focus.md \
--post-scan-prompt-file follow-up.md

例如，使用扫描提示聚焦授权边界，并要求后续操作在扫描目录中写入新的 post-scan-summary.md。扫描被取消或达到成本上限后，后续指令不会运行。

设置输出和策略选项#

使用以下选项保留工件、保存先前结果或创建机器可读的结果。

参数	说明
`--output-dir DIR`	将扫描工件写入外围 Git 工作树之外的私有目录。默认为持久化 Codex Security 状态。
`--archive-existing`	将现有结果移动到 `DIR.previous--`，并从空输出目录开始。需要 `--output-dir`。
`--fail-on-severity LEVEL`	当已完成扫描报告的发现项达到或超过 `critical`、`high`、`medium` 或 `low` 时，返回退出代码 `1`。
`--max-cost USD`	当扫描的模型成本估算超过指定美元金额时停止扫描。
`--dry-run`	检查仓库、目标、知识库、输出目录和 Codex 配置，但不启动扫描。
`--headless`	显示纯文本进度，而不是交互式扫描仪表板。
`--verbose`	将经过脱敏的生命周期、认证、进度和成本诊断信息输出到 stderr。
`--json`	将清单、发现项、覆盖范围、路径和轮次元数据作为一个 JSON 文档输出。
`--format FORMAT`	以 `toon`、`json`、`yaml` 或 `jsonl` 输出完整扫描结果。
`--full-output`	使用默认结构化输出格式输出完整结果。

成本上限是估算值，并非硬性支出上限。已经进行中的请求可能会在略微超过上限后才完成。如果扫描因成本上限而中止，部分扫描结果仍会保留在磁盘上。

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

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

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

如需在重复使用输出目录前保留先前结果：

bash

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

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

bash

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 解释器：

bash

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

配置运行时#

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

参数	说明
`--auth {auto,chatgpt,api-key}`	选择扫描凭据。默认为 `auto`。
`--provider {openai,openrouter,fireworks,amazon-bedrock}`	选择推理提供商。默认为 `openai`。
`--model MODEL`	选择模型。默认为 `gpt-5.6-sol`。OpenRouter、Fireworks 和 Amazon Bedrock 必须指定。
`--effort {minimal,low,medium,high,xhigh}`	选择模型的推理强度。默认为 `xhigh`。
`--plugin-path PATH`	使用 Codex Security 插件目录或 ZIP 覆盖捆绑插件。
`--python PATH`	为插件运行时选择 Python 解释器。
`--codex KEY=VALUE`	覆盖隔离的 Codex 配置值。值使用 TOML 语法。如需设置多个值，请重复使用此标志。

如需在不编写 TOML 的情况下选择不同的模型和推理强度：

bash

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

请将通过 --codex 传递的字符串值用引号括起来，以便 TOML 解析器收到字符串：

bash

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

`codex-security install-hook`#

为当前仓库安装 Git 提交前安全检查：

bash

npx @openai/codex-security install-hook

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

bash

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

`codex-security bulk-scan`#

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

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

text

usage: codex-security bulk-scan [input] [--output-dir DIR]
[--workers N] [--mode {standard,deep}]
[--provider {openai,openrouter,fireworks,amazon-bedrock}]
[--model MODEL]
[--effort {minimal,low,medium,high,xhigh}]
[--knowledge-base PATH]
[--scan-prompt-file FILE]
[--post-scan-prompt-file FILE]
[--max-attempts N] [--plugin-path PATH]
[--python PATH] [--codex KEY=VALUE]

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

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

bash

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

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

bash

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

CSV 必须包含 id、repository 和 revision 列。修订版本必须是完整的提交哈希。可选的 scope、mode 和 prompt 列可配置各个仓库：

csv

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

使用 --knowledge-base PATH 在所有仓库之间共享安全文档。使用 --scan-prompt-file FILE 添加共享扫描指令；CSV 的 prompt 列会在该共享提示后添加仓库专属指令。 --post-scan-prompt-file FILE 会在每次扫描后运行后续指令，包括覆盖范围不完整或出错的扫描；扫描被取消或达到成本上限后不会运行。

--workers 限制同时运行的仓库扫描数，默认为 4。--mode 默认为 standard，--max-attempts 默认为 1。设置 --max-attempts 可重试仓库或扫描错误。覆盖范围不完整的已完成扫描不会重试。其结果仍然可用，并且命令会返回退出代码 2。

再次运行同一命令可从现有输出目录恢复。CLI 会跳过已完成的扫描，包括覆盖范围不完整的扫描。

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

`codex-security scans`#

查找已保存的扫描#

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

bash

npx @openai/codex-security scans

列出其他仓库的扫描：

bash

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

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

bash

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

检查或重复扫描#

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

bash

npx @openai/codex-security scans show SCAN_ID

添加 --show-linked-findings，可以包含较早扫描中的发现链接。

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

bash

npx @openai/codex-security scans rerun SCAN_ID

检查已保存的扫描日志#

读取某次扫描及其 workers 保存的完整 session 事件：

bash

npx @openai/codex-security scans logs SCAN_ID

添加 --json 可以获得包含完整信息的机器可读结果。

匹配和比较发现项#

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

bash

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

比较会自动匹配具有相同根本原因的发现项，并复用已保存的匹配。如需显式保存匹配，请使用 scans match：

bash

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

如果后一次扫描的覆盖范围不完整，或未覆盖发现项的原始位置，该发现项即为未知。需要重新计算现有匹配时，请向 match 添加 --force。

如需匹配当前仓库的所有已完成扫描，包括来自其他检出的扫描：

bash

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

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

`codex-security findings`#

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

bash

npx @openai/codex-security findings list

传入仓库路径可以检查另一个 checkout：

bash

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

添加 --json 可以获得结构化输出。列表会标明最新扫描中出现的发现，以及未在最新扫描中确认的较早发现。

请注意，较早的发现会一直保持 open，直到被解决或驳回；没有出现在最新扫描中，并不能证明它已修复。

要把经过评审的发现记录为误报：

text

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

检查已保存的扫描，以识别该发现项的具体出现位置：

bash

npx @openai/codex-security scans show SCAN_ID

为误报记录具体说明：

bash

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 运行时和凭据。

text

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 写入文件：

bash

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：

bash

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

将发现项导出为 JSON：

bash

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

将发现项导出为 CSV：

bash

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

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

检查候选发现项是否有效：

bash

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

使用捆绑的修复技能生成修复方案：

bash

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

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

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

bash

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

`codex-security login`、`logout` 和 `info`#

交互式登录：

bash

npx @openai/codex-security login

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

bash

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

检查当前登录状态：

bash

npx @openai/codex-security login status

移除已存储的登录信息：

bash

npx @openai/codex-security logout

通过 stdin 传入 API key 以进行存储：

bash

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

存储企业访问令牌：

bash

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

检查只读的 SDK 和捆绑插件元数据：

bash

npx @openai/codex-security info --json

将 CLI 作为 MCP 服务器公开时，info 是唯一可用的命令。扫描、导出、登录、验证和修复仍只能通过 CLI 完成。

读取扫描输出#

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

交互式终端会显示实时仪表板，其中包含当前扫描阶段、已审查文件、活动、令牌用量和估算成本。CI 和重定向的输出使用纯文本进度。在交互式终端中添加 --headless 可使用纯文本进度：

bash

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

详细诊断#

添加 --verbose 可将经过脱敏的生命周期、认证、进度和成本诊断信息输出到 stderr：

bash

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

设置 CODEX_SECURITY_LOG_LEVEL=debug 可在不使用该标志的情况下启用相同的诊断。CODEX_SECURITY_LOG_LEVEL 未设置时， LOG_LEVEL=debug 也会启用诊断。

完成摘要#

扫描完成后，会将仓库中仍为 open 的发现总数、严重性明细、覆盖范围、耗时、报告路径和结果目录写入 stderr。如果可用，还会包含令牌用量和估算成本：

text

REPORT    /path/to/scan/report.md

FINDINGS  4 (3 confirmed this scan; 1 previously found; 1 critical, 2 high, 1 informational)
COVERAGE  complete
ELAPSED   1s
TOKENS    1,250 input, 200 cached, 30 output
RESULTS   /path/to/scan

信息性发现项计入摘要总数。严重性策略只评估当前扫描中的 critical、high、medium 和 low 发现，不评估仓库总数中显示的较早发现。

JSON 输出#

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

text

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

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

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

扫描工件#

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

text

<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 登录信息。对于 OpenRouter 或 Fireworks，请设置提供商的 API key 并选择模型。对于 Amazon Bedrock，请改用 Bedrock API key 或标准 AWS 凭据链。

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

对于 CI，请将 API key 的作用域限制在扫描步骤内，并使用可信的工作流。

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

接下来可参阅 CLI 快速入门、批量扫描指南、CLI 常见问题、CI 指南或 TypeScript SDK 指南。

纯文本别名#

--output FILE|-

本站实践建议#

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

Codex API 与国内使用#

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

Codex Security CLI 参考#

命令概览#

发现命令并连接智能体#

codex-security scan#

选择扫描认证方式#

使用 OpenRouter 或 Fireworks#

使用 Amazon Bedrock#

选择扫描目标#

配置深度扫描#

添加安全上下文#

添加扫描指令#

设置输出和策略选项#

配置运行时#

codex-security install-hook#

codex-security bulk-scan#

codex-security scans#

查找已保存的扫描#

检查或重复扫描#

检查已保存的扫描日志#

匹配和比较发现项#

codex-security findings#

codex-security export#

codex-security validate 和 codex-security patch#

codex-security login、logout 和 info#

读取扫描输出#

详细诊断#

完成摘要#

JSON 输出#

扫描工件#

退出代码和信号#

认证和先决条件#

纯文本别名#

本站实践建议#

Codex API 与国内使用#

`codex-security scan`#

`codex-security install-hook`#

`codex-security bulk-scan`#

`codex-security scans`#

`codex-security findings`#

`codex-security export`#

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

`codex-security login`、`logout` 和 `info`#